Programadores

Cobrar marcações a partir de outro ponto de venda

Deixe um ponto de venda externo ler quanto dá uma marcação e devolver a venda, para a marcação ficar concluída.

O que é

A passagem de cobrança (checkout hand-off) é um só endereço com duas chamadas: GET e POST /api/v1/{slug}/appointments/{id}/checkout. O GET devolve quanto dá a marcação: cada serviço e extra com o seu lineId e quem o fez, o preço, os descontos, as linhas de imposto, o sinal já pago, e dueCents, que é exatamente o que deve cobrar. O POST regista a venda que o seu ponto de venda fez, conclui a marcação e associa-lhe a venda, usando o mesmo código de cobrança que o ponto de venda do próprio Bookatu.

Porque ajuda

Ninguém regista uma visita duas vezes, e a marcação, a venda, o crédito da equipa e o dinheiro batem certo no Bookatu como se tivesse sido o próprio ponto de venda dele a cobrar. O envio é idempotente no seu externalSaleId, por isso uma nova tentativa depois de uma ligação cair devolve replayed: true e não escreve nada.

Como se usa

  1. 1Os proprietários e os administradores criam a chave em Settings, depois «API & monitoring», em «API keys». Em «What this key may do», assinale as duas caixas da linha «Checkout at another point of sale»: «See what a booking comes to at checkout (checkout:read)» e «Check bookings out from another point of sale (checkout:write)». Só ficam ativas se as escolher, e uma chave criada antes dos âmbitos nunca as tem. Quem cria a chave tem de poder ver a agenda de toda a gente (para checkout:read) e editar a agenda (para checkout:write). Acrescente «See bookings (bookings:read)» para listar as marcações do dia com GET /appointments, e «See clients (customers:read)» se o seu ponto de venda precisar do nome, do email e do telefone do cliente. Sem isso, o cliente vem só pelo id.
  2. 2Envie a chave como Authorization: Bearer em cada chamada. Chame GET /api/v1/{slug}/appointments/{id}/checkout e registe as linhas. checkout.allowed diz se a marcação pode ser cobrada agora, e checkout.blocked dá o motivo: not_live, deposit_pending, already_checked_out ou invoiced. invoiced quer dizer que a marcação está numa fatura e é paga lá, por isso não cobre dinheiro por ela no seu ponto de venda.
  3. 3Receba o dinheiro e depois faça POST para o mesmo endereço com { externalSaleId, source, amountCents, currency, tender, tipCents, tipSplit, lines }. externalSaleId é o id da venda no seu próprio ponto de venda. source identifica o seu ponto de venda, como front_desk_pos (por defeito é external e nunca pode ser bookatu). amountCents tem de ser igual a dueCents. currency é opcional, mas tem de ser a do negócio. tender é card, cash ou other. lines, como [{ lineId, staffId }], atribui uma linha a outra pessoa.
  4. 4Enviar outra vez o mesmo externalSaleId a partir do mesmo ponto de venda devolve a venda original com replayed: true. As recusas não escrevem nada e dão um motivo: 400 card_number (externalSaleId ou source parece um número de cartão, o que nunca é aceite); 409 amount_mismatch (com expectedCents), already_checked_out, external_sale_used, lines_changed (leia a cobrança outra vez), not_live, deposit_pending ou invoiced (a marcação é paga na fatura); 422 currency ou tip_split; 503 enquanto a passagem de cobrança ainda está a ser ativada para o negócio.
  5. 5Para saber de cada cobrança, adicione um webhook no cartão Webhooks da mesma página e assinale booking.checked_out em «Only if you tick it». Nunca é enviado para um endpoint que recebe todos os eventos. Também dispara nas cobranças feitas no ponto de venda do próprio Bookatu (sale.source bookatu), com o mesmo conteúdo que o GET e o cliente só pelo id.
  6. 6A referência completa, com todos os campos e exemplos, está na documentação para programadores em /developers#checkout-handoff, e em markdown em /developers.md.

Was this helpful?

Não encontrou o que precisava?

Contactar o suporte ou consulte as perguntas frequentes.