O canal Manual/API

Quando usar um canal Manual/API

Um canal Manual/API não está ligado a nenhuma loja. Nada é carregado para um site e nenhuma encomenda chega sozinha. Usa-o quando:

• Vendes no teu próprio site, num marketplace a que não nos ligamos, nas redes sociais ou por telefone, e queres enviar-nos cada encomenda tu mesmo.
• Tens o teu próprio sistema ou programador e queres enviar-nos encomendas através da nossa API.

Se a tua loja está numa plataforma mostrada na página Add Sales Channel, como Shopify, WooCommerce, eBay ou TikTok Shop, liga essa plataforma em vez disso. Depois os produtos são carregados por ti e as encomendas chegam sozinhas.

Podes ter mais do que um canal Manual/API, por exemplo um por site.

Criar o canal

1. Abre Channels no menu. Vês a lista dos teus Sales Channels.
2. Clica em Add Sales Channel. A página mostra Select channel you want to create.
3. No cartão Manual/API clica em Create.
4. Abre-se uma janela Create platform manual. Escreve um nome para o canal, por exemplo o nome do teu site. O nome pode ter até 28 caracteres.
5. Clica em Create.

Vês a mensagem Your Manual store has been created. e a página do canal abre-se.

Cada um dos teus canais precisa do seu próprio nome. Se o nome já for usado por outro dos teus canais, a janela mostra um erro. Escolhe um nome diferente.

A página do teu canal

A página do canal tem o nome do teu canal como título e o cabeçalho Manual/API order management. Mostra três caixas, cada uma com uma ligação View all:

• Orders: as encomendas que colocaste neste canal.
• Clients: as pessoas a quem envias encomendas.
• Products: os produtos na tua lista My Products.

No menu, por baixo do nome do canal, encontras:

• Baskets: encomendas que começaste e ainda não pagaste.
• My Products: os produtos que vendes neste canal. Vê Gerir produtos no canal Manual/API.
• Clients: os teus compradores. Vê Gerir clientes.
• Orders: as tuas encomendas colocadas. Vê Colocar encomendas manualmente.
• API: tokens e documentação para ligares o teu próprio sistema.

A forma habitual de trabalhar é:

1. Adiciona os produtos que vendes a My Products com Add products. Isto é necessário para a API. Para encomendas que escreves tu mesmo é opcional: o cesto deixa-te escolher qualquer produto que vendemos.
2. Quando recebes uma encomenda, abre Clients, encontra o teu comprador ou adiciona-o.
3. Na página do cliente clica em Create Order, adiciona os produtos e quantidades e paga.

Mudar o nome ou fechar o canal

Para renomeares o canal, clica em Edit na página do canal e muda Store name.

Para fechares um canal, vai a Channels e clica no botão de fechar na coluna Action (dica Close channel). A janela pergunta Are you sure you want to close this channel? e avisa This operation is irreversible. Um canal fechado sai do menu. As tuas encomendas e faturas anteriores mantêm-se.

Ligar o teu próprio sistema com a API

A API deixa o teu site ou aplicação fazer sozinho o que fazes nas páginas do canal: ler o nosso catálogo de produtos com preços em tempo real, adicionar produtos a My Products, criar e mudar clientes, criar encomendas, adicionar-lhes produtos, submetê-las e acompanhá-las. Também podes descarregar a tua lista My Products como um feed CSV ou JSON para carregar produtos para o teu próprio site.

Abre API no teu canal. A página tem estas abas:

• Overview: como ligar, o endereço base da API e o botão API documentation. A documentação lista todos os endpoints com exemplos.
• API tokens: os tokens deste canal.
• API calls: os pedidos que o teu sistema fez.
• History: alterações feitas na tua conta.

Obter um token

1. Clica em Generate API token.
2. Se o token for só para ler dados, marca Read only (cannot create, change or submit orders).
3. Clica em Click to Generate.
4. Copia o token com o ícone de copiar e guarda-o em local seguro. A janela diz Put this token in a safe place, you won't be able to see it again. O rótulo curto na lista de tokens é só um nome, não o token.

Envia o token com cada pedido no cabeçalho Authorization: Bearer seguido do teu token. Cada token pertence a um canal: os produtos, clientes e encomendas que o teu sistema criar vão para esse canal. Para deixares um token de funcionar, apaga-o na aba API tokens.

Testa primeiro em staging

A aba Overview também tem Open staging mirror. O staging é uma cópia separada do site onde podes testar sem encomendas nem pagamentos reais. Faz login com o mesmo e-mail e palavra-passe. O staging é reposto regularmente com uma cópia nova, o que apaga o que aí criaste. Os tokens do site real não funcionam no staging: gera um token separado no staging, e um novo depois de cada reposição. O endereço base do staging aparece na aba Overview.

Como as encomendas da API são pagas

Quando o teu sistema submete uma encomenda, pagamo-la primeiro a partir do saldo da tua conta, depois dos teus cartões guardados. Adiciona um cartão antes de começares. Assim que tiveres um token, o menu mostra Saved Cards. Enquanto nenhum cartão estiver guardado, a página API mostra You have no cards saved yet. com um botão Add card.

Se nem o teu saldo nem os teus cartões cobrirem a encomenda, a encomenda fica marcada Unpaid e não vai para o armazém. Adiciona dinheiro ao teu saldo com Top Up, abre a encomenda e clica em Pay … with balance. O botão aparece quando o teu saldo cobre o valor em falta.

Quando algo corre mal

• O nome já está em uso quando crio o canal. Outro dos teus canais abertos tem esse nome. Escreve um nome diferente. O nome de um canal fechado pode ser usado de novo.
• As minhas encomendas não estão a chegar sozinhas. Um canal Manual/API nunca recolhe encomendas de um site. Cria-as na página do cliente, ou envia-as do teu sistema através da API. Se vendes numa plataforma mostrada na página Add Sales Channel, liga essa plataforma como o seu próprio canal.
• Os meus produtos não estão no meu site. Não carregamos nada a partir de um canal Manual/API. Carrega-os para o teu site tu mesmo, com a descarga CSV em My Products ou através da API.
• Perdi o meu token da API. Não pode voltar a ser mostrado. Gera um token novo, coloca-o no teu sistema e apaga o antigo.
• A API responde que não posso criar ou mudar encomendas. O token é só de leitura. Gera um token sem Read only marcado.
• A API recusa os meus pedidos durante um pouco. Cada token pode fazer até 120 pedidos por minuto. Abranda o teu sistema e tenta de novo passado um minuto.
• A API diz "This order has no products yet". ("Esta encomenda ainda não tem produtos.") Adiciona pelo menos um produto à encomenda antes de a submeteres.
• A API diz "Unable to find related portfolio item". ("Não foi possível encontrar o artigo de portefólio relacionado.") Através da API adicionas um produto a uma encomenda pelo seu artigo em My Products, não pelo próprio produto. Adiciona primeiro o produto a My Products e usa o id desse artigo.
• A API diz que já existe outra transação com o mesmo produto. O produto já está na encomenda. Muda a quantidade dessa linha em vez de o adicionares outra vez.
• A API diz que a encomenda "is already in the 'submitted' state and cannot be updated". ("já está no estado 'submitted' e não pode ser atualizada.") As encomendas submetidas não podem ser mudadas nem apagadas através da API. Pergunta-nos no chat do nosso site se a encomenda tiver de mudar.
• A minha encomenda da API mostra Unpaid. O teu saldo e os cartões guardados não a cobriram. Recarrega o teu saldo, abre a encomenda e clica em Pay … with balance, e verifica que o teu cartão guardado ainda é válido.