Ir para o conteúdo

A API de agendamento aberta a todas as suas ferramentas

Tokens com âmbitos, webhooks assinados, aplicações OAuth, Zapier e Make. As suas marcações circulam onde trabalha.

Uma API de agendamento é útil assim que as suas marcações precisam de viver fora da ferramenta de marcação: um software de gestão, uma extranet de clientes, um armazém de dados, uma ferramenta de automação. Sem ela, só resta a exportação manual e voltar a introduzir os dados.

Porque uma API de agendamento completa

O Artibox Calendar expõe uma API REST pública nas suas rotas /api/v1: tipos de marcação, disponibilidades, marcações, sondagens, ligações únicas, envios de ligações, webhooks. Segue as mesmas regras que a aplicação: as mesmas permissões, o mesmo isolamento entre organizações, a mesma marcação com bloqueio. O que um token pode fazer, o seu membro pode fazer; nada mais.

Para equipas sem programador, os conectores Zapier e Make ligam as suas marcações às suas ferramentas sem escrever código. E para o HubSpot, o Salesforce ou o Pipedrive, as integrações CRM já estão prontas.

Como funciona

  1. Crie um token pessoal

    Escolha os seus âmbitos (ler as marcações, escrever os tipos…). O token começa por rdv_pat_.

  2. Chame a API

    Envie o token no cabeçalho x-api-key. Fora dos seus âmbitos, a chamada é recusada.

  3. Subscreva os eventos

    Declare um endereço de webhook e os eventos que lhe interessam.

  4. Acompanhe as entregas

    O registo dos webhooks mostra cada envio; pode testar e repetir.

Uma API pensada para produção

Tokens com âmbitos

Cada token pessoal tem âmbitos precisos: ler o utilizador, ler ou administrar a organização, ler ou escrever os tipos, ler as disponibilidades, ler ou escrever as marcações, escrever as ligações, gerir os webhooks. Uma chamada fora do âmbito recebe uma resposta 403. Um token nunca pode criar outro token.

Limites claros

Cada token pode fazer 100 chamadas por minuto. As listas são paginadas por número de página. As criações aceitam um cabeçalho Idempotency-Key, guardado 24 horas: uma chamada repetida após uma falha de rede não cria duplicados. As marcações criadas pela API têm a origem «api».

O mesmo motor que a página de marcação

Uma marcação criada pela API segue as mesmas regras que na sua página de marcação online: antecedência, intervalos, máximo por dia, calendários ligados. Se o horário acabou de ser ocupado, a resposta é uma recusa clara, nunca uma marcação duplicada.

Webhooks assinados

Os eventos

A sua aplicação é avisada quando uma marcação é criada, alterada, cancelada ou registada, quando um convidado vota numa sondagem ou uma sondagem é confirmada, e quando um tipo muda. Cada envio é assinado (cabeçalho X-Signature): verifica que vem mesmo do Artibox Calendar.

Entregas fiáveis

Se o seu servidor não responder, a entrega é repetida, de um minuto a doze horas. Após 20 falhas consecutivas, a subscrição é desativada. O registo guarda 30 dias de entregas; um botão envia um evento de teste e outro repete uma entrega. Por segurança, os webhooks não podem apontar para um endereço da rede interna.

OAuth para fabricantes de software

Desenvolve uma ferramenta usada por outras organizações? Declare uma aplicação OAuth em Definições › Integrações. Os seus utilizadores veem um ecrã de consentimento e, depois, a sua aplicação recebe um código de utilização única, válido 10 minutos, protegido por PKCE (S256). O token de acesso dura 2 horas; o token de atualização roda a cada utilização, e a sua reutilização corta todo o acesso. Cada membro retira um acesso a partir de «Aplicações ligadas».

Sem código: Zapier, Make e o widget

Zapier e Make

Os conectores Zapier e Make ligam-se como aplicações OAuth: desencadeie um cenário a cada nova marcação, envie uma ligação de marcação a partir de outra ferramenta, procure uma marcação por e-mail.

O kit de integração

O script widget.js adiciona um botão ou uma ligação de marcação ao seu site. A marcação abre-se numa janela à parte. Os parâmetros de acompanhamento (utm_*, gclid, fbclid, ref) são guardados na marcação, e um contexto assinado pode pré-preencher a marcação a partir da sua ferramenta.

Planos e segurança

A API (tokens pessoais, aplicações OAuth) e os conectores Zapier e Make fazem parte do plano Pro; os webhooks, do plano Equipa. O detalhe está na página de preços. Só é guardada a impressão digital dos tokens, nunca o token em claro: veja segurança e RGPD.

Para começar, siga a ajuda API e tokens (FR) e webhooks (FR). Para escolher entre as duas ferramentas de automação, leia Zapier ou Make (FR). Definições: API (FR), webhook (FR).

Para quem

  • Equipas comerciais

    Ligar as marcações às suas ferramentas de vendas e de reporting.

  • Agências (FR)

    Integrar o agendamento nos sites e nas ferramentas dos seus clientes.

  • Recrutamento (FR)

    Criar as entrevistas a partir do seu software de gestão de candidaturas.

  • Formadores (FR)

    Enviar as inscrições nas sessões para a sua ferramenta de gestão da formação.

Perguntas frequentes

Como me autentico na API de agendamento?

Com um token pessoal (rdv_pat_…) ou um token de acesso OAuth, enviado no cabeçalho x-api-key. Cada token tem os seus âmbitos.

Quais são os limites de chamadas?

100 chamadas por minuto e por token. As criações aceitam um cabeçalho Idempotency-Key, guardado 24 horas.

Como verificar que um webhook vem mesmo do Artibox Calendar?

Cada envio é assinado no cabeçalho X-Signature. Verifique a assinatura antes de tratar o conteúdo.

O que acontece se o meu servidor estiver indisponível?

A entrega é repetida de um minuto a doze horas. Após 20 falhas, a subscrição é desativada; pode repetir as entregas a partir do registo, guardado 30 dias.

Em que plano está incluída a API?

A API, o Zapier e o Make a partir do plano Pro; os webhooks a partir do plano Equipa. Veja os preços.

Ligue as suas marcações às suas ferramentas

Crie a sua conta gratuitamente e depois o seu primeiro token de API.

Criar a minha conta