Referência da API

A API v1 do ByDomu é REST com JSON. Esta referência é gerada a partir da spec OpenAPI, que por sua vez sai do código das rotas: cada endpoint traz seus parâmetros, a permissão que pede e exemplos. Não há SDK oficial; com a spec você pode gerar seu cliente.

Endereço base

https://api.bydomu.com/v1

OpenAPI

openapi.json · v3.1.0

Esta referência é gerada a partir do código da API, por isso as descrições estão em espanhol. Nomes, parâmetros e exemplos são iguais em qualquer idioma.

Autenticação

A chave vai no cabeçalho X-API-Key (Authorization: Bearer não é aceito). Ela é criada no ByDomu, em Configurações › API Keys, e a completa aparece uma só vez.

cURL

curl https://api.bydomu.com/v1/me \
  -H "X-API-Key: $BYDOMU_API_KEY"

domu_pk_live_publicável

Para sites e o navegador. Só: portal:read, leads:write, booking:write, finder:write, events:write.

domu_sk_live_secreta

Só de um servidor: com Origin (navegador) responde 403 SECRET_KEY_IN_BROWSER. Qualquer permissão.

domu_live_legado

Chaves criadas antes dos tipos. Continuam funcionando igual.

Níveis de acesso

NívelPlanosComo se obtém

1Chaves publicáveis300 requisições e 60 escritas por minuto · até 5 chavesQualquer plano pagoSem solicitação

2Secretas somente leitura60 requisições por minuto · até 2 chavesBusiness · EnterpriseAutomático

3Escritas, mensagens, webhooks e limites altosSob medida do aprovadoQualquer plano pagoRevisão do suporte

Paginação

As listas recebem page (a partir de 1) e pageSize, e respondem com os dados e o total. Cada endpoint informa seu pageSize máximo. Contatos, negócios e tarefas aceitam também cursor.

JSON

{
  "data": [ … ],
  "meta": { "total": 64, "page": 1, "pageSize": 12, "totalPages": 6 }
}

Erros

Sempre com o mesmo formato. Dados que não passam na validação do esquema respondem 400 com a lista de problemas.

JSON

{
  "error": {
    "code": "FORBIDDEN",
    "message": "La API key no tiene el scope requerido: contacts:read"
  }
}

400VALIDATION_ERRORDados de entrada inválidos

401UNAUTHORIZEDChave ausente ou inválida

402PAYMENT_REQUIREDConta somente leitura: escrita recusada

403FORBIDDENA chave não tem essa permissão

403SECRET_KEY_IN_BROWSERChave secreta usada em um navegador

403API_ACCESS_REQUIREDO nível da conta não permite esta chave

403PLAN_LIMIT_REACHEDUm limite do plano foi atingido

404NOT_FOUNDRecurso não encontrado

409IDEMPOTENCY_CONFLICTIdempotency-Key reutilizada com outro corpo

429RATE_LIMITEDLimite por minuto excedido

Limites

Uma chave publicável tem 300 requisições e 60 escritas por minuto; uma secreta, 60 e 30. O suporte pode aprovar mais. Cada resposta traz X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset; ao passar, 429 RATE_LIMITED com Retry-After.