Fundamentos

Paginação por cursor

As listagens usam paginação por cursor e retornam data e has_more. O limite padrão é 25 itens e pode variar de 1 a 100.

{
  "data": [
    {
      "object": "segment",
      "id": "seg_ckxyz123",
      "name": "Clientes VIP"
    }
  ],
  "has_more": true
}

Para buscar a página seguinte, envie o id do último item como starting_after:

curl --get https://api.bevits.com/v1/segments \
  --header "Authorization: Bearer $BEVITS_API_KEY" \
  --data-urlencode "limit=25" \
  --data-urlencode "starting_after=seg_ckxyz123"

Continue enquanto has_more for true. Não reutilize o cursor de um tipo de recurso em outra listagem.

IDs públicos

IDs são opacos e carregam um prefixo que identifica o recurso.

Prefixo	Recurso
`org_`	Organização
`bak_`	API key
`cus_`	Cliente
`seg_`	Segmento
`pur_`	Compra
`tag_`	Tag
`atr_`	Atributo
`flw_`	Flow
`emc_`	Campanha de e-mail

Trate IDs como strings. Não remova o prefixo nem tente inferir seu conteúdo.

Filtros e datas

Filtros são enviados como parâmetros de query. Datas usam ISO 8601 com offset; as respostas são normalizadas para UTC.

curl --get https://api.bevits.com/v1/customers \
  --header "Authorization: Bearer $BEVITS_API_KEY" \
  --data-urlencode "is_subscribed=true" \
  --data-urlencode "updated_since=2026-07-01T00:00:00Z"

Campos sem valor são omitidos das respostas, em vez de retornarem null. Valores monetários usam centavos, como total_spent_in_cents: 15990.

Erros

Erros nunca são retornados com status 200. O campo error.type é estável para automação; message é legível por humanos; request_id identifica a requisição para suporte.

{
  "error": {
    "type": "validation_error",
    "message": "Invalid input: expected number, received NaN",
    "param": "limit",
    "request_id": "req_07f6cdc3c20249d6afcd90b4"
  }
}

HTTP	`error.type`	Significado
`400`	`invalid_request`	Rota, cursor ou formato da requisição inválido.
`401`	`authentication_error`	API key ausente, inválida, expirada ou revogada.
`403`	`permission_denied`	A credencial não possui a permissão necessária.
`404`	`not_found`	O recurso não existe ou não pertence à organização.
`409`	`conflict`	A requisição conflita com o estado atual do recurso.
`422`	`validation_error`	Um parâmetro ou valor não passou pela validação.
`429`	`rate_limited`	O limite de requisições foi excedido.
`500`	`internal_error`	Erro inesperado no servidor.

Rate limit

O limite inicial é de 600 requisições por minuto, por API key. As respostas autenticadas incluem:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 599
X-RateLimit-Reset: 2026-07-25T21:31:00.000Z

Ao receber 429, aguarde o número de segundos indicado em Retry-After antes de tentar novamente. Use backoff com jitter em integrações automatizadas.

Cache condicional

Respostas de recursos incluem ETag. Envie esse valor em If-None-Match para evitar transferir novamente um conteúdo que não mudou:

If-None-Match: "v1-4ad31f5efb6b8f35"

Quando o conteúdo for idêntico, a API responde 304 Not Modified sem corpo.

Primeiros passos

Referência

Fundamentos

Paginação por cursor

IDs públicos

Filtros e datas

Erros

Rate limit

Cache condicional

​Paginação por cursor

​IDs públicos

​Filtros e datas

​Erros

​Rate limit

​Cache condicional

Paginação por cursor

IDs públicos

Filtros e datas

Erros

Rate limit

Cache condicional