Introdução

Como a API REST do Clakta é organizada e as convenções que todo endpoint segue.

O Clakta expõe uma API REST sobre HTTPS. Todo endpoint recebe e retorna JSON, usa verbos HTTP padrão para expressar intenção e códigos de status padrão para o resultado, e é autenticado com uma chave de API enviada como bearer token.

URL base

Todas as requisições vão para um único host:

Os caminhos nesta referência são relativos a esse host, então POST /v1/orders significa POST https://api.clakta.com/v1/orders.

Convenções

Os verbos carregam a intenção. GET lê, POST cria, PATCH atualiza parcialmente, DELETE remove. Um PATCH altera apenas os campos que você enviar.
JSON na entrada e na saída. Envie Content-Type: application/json em qualquer requisição com corpo. As respostas são sempre JSON, inclusive as de erro.
Respostas de sucesso são encapsuladas. Endpoints de escrita retornam uma message legível junto com o recurso afetado em data.
Valores monetários saem como inteiros. Preços são aceitos como decimais (10.4 significa $10,40) e retornados na menor unidade da moeda (1040). Moedas usam códigos ISO 4217.
Datas são ISO 8601 em UTC, por exemplo 2026-07-29T14:03:00.000Z.

Identificando um projeto

A maioria dos endpoints atua em um único projeto, que você pode identificar pelo ID (proj_…) ou pelo slug. Onde o projeto é informado depende do verbo:

Verbo	Onde informar o projeto
`POST`, `PATCH`	`projectId` no corpo JSON
`GET`, `DELETE`	Parâmetro de consulta `projectId`

Uma requisição que aponta para um projeto que sua chave de API não pode acessar retorna 404 not_found em vez de 403, para que a API nunca confirme a existência de recursos aos quais você não tem acesso.

Limites de requisições

As requisições são limitadas por chave de API, por minuto, conforme o plano da sua equipe:

Plano	Requisições / minuto
Free	60
Pro	600
Business	1.200
Enterprise	3.000

Toda resposta traz o estado atual do seu limite:

X-RateLimit-Limit — seu limite na janela
X-RateLimit-Remaining — requisições restantes na janela
X-RateLimit-Reset — quando a janela reinicia
Retry-After — enviado no 429, quanto tempo esperar

Trate 429 rate_limit_exceeded como recuperável: faça backoff exponencial em vez de tentar novamente de imediato.

Erros

Falhas retornam um status fora da faixa 2xx e um corpo JSON descrevendo o problema, incluindo um link para a seção correspondente da referência de erros.

Próximos passos

Autenticação — crie uma chave de API e defina seus escopos
Erros — o que cada código de erro significa e como reagir