API e Webhooks

1. Qual é o meu endereço

Não existe um host único de API. Cada conta é servida no próprio subdomínio, e ele já identifica o cliente: não há parâmetro de conta em nenhuma chamada, e uma credencial só funciona no endereço a que pertence.

Se a sua ouvidoria atende em domínio próprio, ele também serve. O endereço exato aparece em Configurações › API & Webhooks › Referência, já preenchido.

2. Autenticação e escopos

Token no header, em toda requisição:

A chave é criada pelo administrador da conta e mostrada uma única vez. Cada chave carrega os escopos que você escolher, e um escopo que falta devolve 403 dizendo exatamente qual.

3. A primeira chamada

4. Respostas e erros

Toda resposta tem a mesma forma. Sucesso traz ok, data e, nas listagens, meta. Erro traz code, message e request_id:

Códigos possíveis:

5. Idempotência

Mande Idempotency-Key em qualquer escrita. Repetir com a mesma chave devolve a resposta guardada, com o header X-Voxli-Idempotent-Replay: true — nada é criado duas vezes, mesmo que você não saiba se a primeira chegou.

A chave vale para a conta inteira, não por credencial: dois serviços seus usando chaves de API diferentes continuam protegidos entre si. Se uma requisição com a mesma chave ainda estiver em andamento, a segunda recebe 409 idempotency_in_flight em vez de executar em paralelo.

6. Limites

Filtro que a API não consegue interpretar devolve 400 nomeando o parâmetro. Ele nunca é ignorado em silêncio: um since malformado que devolvesse a base inteira seria pior que um erro.

7. Webhooks

Você configura um endereço https público e escolhe os eventos. Cada entrega chega como POST com o mesmo envelope:

Como validar a assinatura

A assinatura é o HMAC-SHA256 de timestamp + ponto + corpo, com o secret do endpoint como chave. O corpo são os bytes crus da requisição: não desserialize e serialize de novo antes de calcular, porque qualquer diferença de espaço, ordem de chave ou escape de acento muda o hash.

Retentativa e duplicidade

Qualquer resposta 2xx é entrega concluída. Fora disso, tentamos 3 vezes, com intervalo de 2, 4 e 8 minutos. O timeout de cada tentativa é de 10 segundos: se o seu processamento demorar mais, responda 200 primeiro e processe depois.

Como a retentativa manda o mesmo corpo, guarde o X-Voxli-Delivery que você já processou e descarte o repetido. Redirect não é seguido, e o endereço precisa ser https e público — endereço interno é recusado.

Eventos disponíveis:

8. Especificação OpenAPI

A especificação completa fica no endereço da sua conta, sem exigir autenticação — dá para apontar um gerador de SDK antes mesmo de criar a primeira chave:

Ela é OpenAPI 3.1, já com o servidor certo em servers, e é verificada contra as rotas reais a cada build: um endpoint que exista e não esteja documentado, ou documentado e não exista, quebra a nossa integração contínua.