Ligue as suas ferramentas a encomendas, stock disponível e rastreio de envios através da API REST, do SDK TypeScript e dos webhooks.
Abra o portal do programador para consultar as API acessíveis à sua conta e o SDK disponível no seu ambiente. É necessário iniciar sessão e ter as permissões adequadas.
TypeScript SDK
Um exemplo TypeScript no servidor com o cliente Ysend. Configure o URL base da API acordado durante a ativação e guarde a chave API nas variáveis de ambiente do servidor.
import { Ysend } from "@ysend/sdk";
const ysend = new Ysend({
baseUrl: process.env.YSEND_API_BASE_URL!,
apiKey: process.env.YSEND_API_KEY!,
});
const stock = await ysend.inventory.listBalances({ page: 1, pageSize: 20 });
const orders = await ysend.orders.list({ status: "Open", page: 1, pageSize: 20 });
const shipments = await ysend.shipments.list({ page: 1, pageSize: 20 });O exemplo requer inventory:read, orders:read e shipments:read. Nas escritas do SDK, forneça um Idempotency-Key estável para permitir novas tentativas sem criar uma segunda operação.
Utilize Node.js 20 ou posterior. Se o portal disponibilizar um SDK, anote a versão e o nome do ficheiro e verifique o SHA-256 da transferência. Substitua PACKAGE_FILE.tgz abaixo por esse nome exato.
npm install ./PACKAGE_FILE.tgzYSEND_API_BASE_URL deve conter a origem da API acordada: protocolo HTTPS e anfitrião, sem /api/v1. O SDK acrescenta esse caminho. Guarde YSEND_API_KEY no servidor; os pedidos utilizam X-Api-Key.
Cada consulta de lista devolve uma página. Indique page e pageSize e consulte items, totalCount, page e pageSize, quando fornecidos, antes de pedir mais páginas. A primeira página não é uma exportação completa.
YsendError apresenta o estado HTTP, detail e traceId disponíveis. YsendTransportError significa que não foi recebida uma resposta utilizável; o resultado de uma escrita pode então ser desconhecido.
Por predefinição: três tentativas no total e 30 segundos de espera pelos cabeçalhos da resposta por tentativa. GET/HEAD e pedidos com Idempotency-Key podem ser repetidos após um erro de rede ou HTTP 429, 502, 503 ou 504. Reutilize a mesma chave para a mesma operação. orders.list utiliza POST sem essa chave e não beneficia destas novas tentativas automáticas.
Sem acesso ou SDK disponível? Descreva as trocas de dados a testar no pedido relativo ao seu projeto. Antes dos testes, confirme a origem da API, a versão do pacote, a referência API aplicável, a conta de teste e as permissões. Não inclua segredos.
Começar
Após a ativação da conta, um administrador autorizado cria uma chave com as permissões necessárias à sua integração.
Se existir um pacote SDK publicado para o seu ambiente, descarregue-o no portal do programador, verifique o SHA-256 e instale o ficheiro descarregado.
Consulte stock, encomendas e envios dentro das permissões atribuídas à sua chave.
Webhooks
Crie subscrições na aplicação, teste-as com um ping e consulte as tentativas de entrega. A outbox repete as tentativas nos erros elegíveis; os eventos que esgotam as tentativas continuam visíveis na fila de falhas.
Âmbito
Importe CSV ou linhas estruturadas; consulte, corrija e volte a enviar as linhas rejeitadas.
Associe SKU e consulte o stock físico, reservado e disponível.
Prepare planos de entrada, adicione linhas, solicite horários de entrega e acompanhe divergências na receção.
Consulte a transportadora, o rastreio e o estado da entrega após a criação do envio durante a preparação.
Abra um processo associado a uma encomenda e anexe fotografias ou documentos.
Consulte subscrições e o histórico de entrega a partir da sua integração.
Chaves de parceiro
Guarde as chaves no servidor. As permissões de conta e de parceiro delimitam cada operação; os administradores autorizados gerem a criação e rotação de chaves e as subscrições webhook no portal correspondente.
Apresente os seus fluxos de dados e as operações necessárias. Confirmaremos os acessos, as permissões e o pacote SDK para a sua integração.
A equipa Ysend ajuda a definir os serviços, as ligações e o calendário para o seu negócio.