Construa sobre os seus dados de calibração.

A API pública do Axiospec é uma interface REST para o seu programa de calibração. Leia e crie instrumentos, registre calibrações no registro com detecção de adulteração e leia os locais do seu espaço de trabalho e as normas de conformidade que você selecionou.

É um contrato curado e estável, separado dos endpoints internos que os apps web e móvel usam, então sua integração continua funcionando conforme o produto evolui. Toda resposta é JSON.

Todos os endpoints ficam sob uma única URL base. Cada caminho da referência abaixo é relativo a ela.

Autentique cada requisição com uma chave de API do espaço de trabalho. Um administrador do espaço de trabalho cria a chave no app, em Configurações e depois Chaves de API. As chaves aparecem uma única vez, na criação, e têm o prefixo ctk_. Guarde a chave como um segredo e nunca a publique em código que roda no cliente.

Envie a chave em toda requisição como bearer token:

O cabeçalho padrão X-API-Key também é aceito, se você preferir: X-API-Key: ctk_your_api_key. Uma requisição sem chave retorna 401.

A API está disponível nos planos Professional e acima. Uma chave de um espaço de trabalho no plano Free ou Starter recebe 403 com o código API_ACCESS_TIER_REQUIRED. Mude o plano do espaço de trabalho para liberá-la.

Cada chave é emitida com um escopo. Uma chave de leitura lista e consulta. Uma chave de escrita também cria instrumentos, atualiza instrumentos e registra calibrações (escrita sempre implica leitura).

Uma chave somente leitura que tenta escrever recebe 403 com o código INSUFFICIENT_SCOPE, nomeando o escopo necessário. Emita chaves somente leitura para integrações de relatório, assim elas nunca conseguem alterar um registro.

As requisições são limitadas a 120 por minuto, contadas por chave de API e não por IP, então uma integração não sufoca a outra e várias chaves atrás de uma mesma rede de escritório não são limitadas juntas.

Toda resposta da API carrega a janela atual em cabeçalhos, então você acerta o ritmo sem adivinhar. X-RateLimit-Limit é o teto (120), X-RateLimit-Remaining é quantas requisições restam na janela atual e X-RateLimit-Reset é quantos segundos faltam até a janela reiniciar e Remaining voltar ao limite cheio.

Passar do limite retorna 429 com o código RATE_LIMITED. No 429, o cabeçalho Retry-After (em segundos) diz exatamente quanto esperar. Respeite-o e tente de novo. Ler esses cabeçalhos, em vez de fixar um atraso no código, mantém você rápido quando há folga e educado quando não há.

Para manter um sistema externo em dia sem reler tudo, puxe só o que mudou desde a sua última execução. Cada coleção aceita o parâmetro updated_since (um timestamp ISO-8601 em UTC) que retorna apenas os registros modificados naquele instante ou depois, além do parâmetro sort, para você percorrer do mais antigo ao mais novo e avançar um marcador conforme anda.

O feed de calibrações de todo o espaço de trabalho, GET /calibrations, foi feito exatamente para isso: devolve todas as calibrações de todos os seus instrumentos em um único fluxo paginado, então você não precisa percorrer instrumento por instrumento. Ordene por updated_at de forma crescente, pagine e guarde o created_at do último registro que viu. O registro é apenas de acréscimo, então um registro de calibração nunca muda depois de escrito e o created_at dele é a hora da última modificação. sort=updated_at aponta para esse instante.

Na execução seguinte, passe o valor guardado como updated_since. Sobreponha a fronteira em um ou dois segundos e descarte duplicatas pelo id do registro, para se proteger de diferenças de relógio. Guarde o marcador só depois de ter processado a página de forma durável.

Instrumentos aceitam os mesmos parâmetros updated_since e sort (GET /instruments), filtrando pela hora da última modificação do instrumento. As linhas da lista não trazem um campo de timestamp, então, para instrumentos, use como próximo updated_since a hora de relógio que você capturou logo antes da requisição. O GET /instruments/{id} de um único instrumento retorna created_at e updated_at, se você precisar deles.

GET /instruments aceita filtros para você buscar uma fatia precisa em vez de paginar a lista inteira. asset_tag e serial_number casam com um valor exato (útil para conferir um instrumento contra um registro do ERP). status filtra pelo estado no ciclo de vida, por exemplo active ou retired. site_id restringe a um local.

Dois filtros vêm do estado de calibração. compliance_status filtra pelo token calculado, um entre COMPLIANT, WARNING, NON_COMPLIANT ou NOT_CALIBRATED. next_due_before recebe uma data (YYYY-MM-DD) e retorna os instrumentos cuja próxima calibração vence antes dela, que é a consulta por trás de uma lista de vencimentos próximos ou em atraso. Os filtros se combinam, então você pede instrumentos ativos e não conformes em um local em uma única chamada.

Registrar uma calibração é a única escrita que nunca pode ser duplicada: o registro é apenas de acréscimo, então não há como desfazer um envio em dobro. Por isso POST /instruments/{id}/calibrations exige o cabeçalho Idempotency-Key (qualquer string única que você gerar, por exemplo um UUID). Ele é obrigatório, não opcional.

Se uma requisição for interrompida e você tentar de novo com a mesma chave, a API devolve o registro que já escreveu em vez de escrever um segundo. Uma chave ausente retorna 400 com o código IDEMPOTENCY_KEY_REQUIRED. Gere uma chave nova para cada calibração que pretende registrar.

Criar um instrumento (POST /instruments) também respeita um Idempotency-Key, mas aqui ele é opcional. Envie um e uma nova tentativa com a mesma chave devolve o instrumento que a primeira chamada criou, em vez de um duplicado, exatamente como no log de calibração. A única diferença é que a chave não é obrigatória. Se você preferir não gerenciar chaves nas criações, dá para remover duplicatas do seu lado usando o asset_tag ou o serial_number do instrumento, que são únicos dentro de um espaço de trabalho, antes do POST.

Toda calibração aprovada tem um certificado em PDF com a sua marca. Busque-o com GET /calibrations/{calibration_id}/certificate. A resposta é o próprio PDF (Content-Type application/pdf) como anexo, idêntico byte a byte ao certificado que o app produz, então você pode arquivá-lo ou anexá-lo a uma ordem de serviço.

Um certificado existe apenas para uma calibração aprovada e vigente. Se o registro foi anulado, substituído por um lançamento posterior ou não é certificável por outro motivo, a requisição retorna 404 com o código CERTIFICATE_UNAVAILABLE. Um id de calibração que não é seu, ou que não existe, retorna um 404 simples que não revela nada sobre ele.

Quando um instrumento sai de serviço, desative-o com POST /instruments/{id}/retire (uma chamada de escopo de escrita). É uma baixa suave: o status do instrumento passa a retired e ele sai da lista padrão de ativos, mas nada é apagado e o histórico de calibração dele no registro fica intacto para auditoria. Não existe exclusão definitiva na API.

A chamada devolve o instrumento atualizado. Ela é idempotente: desativar um instrumento já desativado não faz nada e devolve o mesmo registro desativado, então repetir é sempre seguro. Desativar exige uma chave de gerente ou de administrador. Uma chave somente leitura ou de técnico recebe 403.

Os endpoints de listagem devolvem um envelope consistente. Pagine os resultados com os parâmetros de consulta limit e offset. total é a contagem completa e has_more diz se existe outra página.

Todo timestamp que a API devolve é ISO-8601 em UTC, terminando em Z, por exemplo 2026-07-09T15:30:00Z. Envie os timestamps do mesmo jeito. Não há respostas com offset nem com hora local para normalizar.

Um campo é uma data simples, não um timestamp: a data de vencimento da calibração de um instrumento. As datas de vencimento são calculadas no fuso horário configurado no seu espaço de trabalho, então uma data de vencimento é o dia do calendário em que ela vence lá, e o filtro next_due_before recebe uma data (YYYY-MM-DD), não um timestamp. Se seus sistemas rodam em outro fuso, compare pela data, não por um instante de meia-noite em UTC.

Todo erro, em todo endpoint, tem o mesmo formato JSON: um code legível por máquina, uma message legível por pessoas e, em alguns erros, um objeto details com as especificidades. Ramifique pelo code, nunca pelo texto da message, que pode ser reescrito. O status HTTP continua tendo significado (401 contra 403 contra 404), então use-o também.

Registrar uma calibração também aplica as exigências de campo das normas que o seu espaço de trabalho selecionou. Se um campo obrigatório estiver em branco, a requisição retorna 422 com o código FIELD_REQUIREMENTS_UNMET e um array missing_fields, em que cada item nomeia o campo e qual norma o exige, para você pedir exatamente o que falta.

Em vez de consultar a API de tempos em tempos para descobrir o que mudou, inscreva um endpoint de webhook uma vez e o Axiospec entrega cada evento na sua URL assim que ele acontece. Você ganha menos latência e muito menos tráfego desperdiçado do que relendo coleções que já viu, e nunca perde uma mudança entre duas consultas.

Inscreva com POST /webhooks, passando uma url e uma lista opcional de tipos de evento a receber. Omita o campo events para receber todos os eventos (o catálogo completo está abaixo). A resposta devolve o segredo de assinatura do endpoint exatamente uma vez e nunca mais, então copie-o direto para o seu cofre de segredos. Gerenciar webhooks exige uma chave de escrita de administrador ou de gerente, porque o endpoint recebe os dados de calibração e de instrumentos do seu espaço de trabalho.

Cada evento é entregue como um POST HTTP cujo corpo JSON é um envelope fixo: { "id", "type", "created_at", "data" }. O id é o id estável do evento, enviado também no cabeçalho Axiospec-Event-Id, junto de Axiospec-Event-Type, Axiospec-Webhook-Id e Axiospec-Delivery-Attempt. A entrega é pelo menos uma vez, então o mesmo evento pode chegar mais de uma vez (por exemplo depois de uma nova tentativa). Remova duplicatas pelo id do envelope.

Uma entrega conta como falha em qualquer resposta que não seja 2xx, e isso inclui um redirecionamento 3xx: um redirecionamento poderia apontar para um endereço interno, então ele nunca é seguido. Erros de transporte e tempos esgotados também contam como falha. As entregas com falha são repetidas com espera exponencial ao longo de cerca de três dias, e depois disso a entrega é marcada como esgotada. Um endpoint cujas entregas recentes se esgotam todas é desativado automaticamente, para que uma URL morta ou hostil pare de consumir capacidade. Os endpoints precisam ser HTTPS, e uma URL que resolve para um endereço privado ou interno é recusada na inscrição.

Veja o que foi enviado com GET /webhooks/{id}/deliveries, que pagina o log de entregas de um endpoint e aceita um filtro status (pending, failed, succeeded, exhausted). Para repetir uma entrega, use POST /webhooks/{id}/deliveries/{delivery_id}/retry: ele volta a entrega para pending e vencida agora, para que o próximo disparo reenvie, com um novo horizonte de tentativas. Troque o segredo de um endpoint com POST /webhooks/{id}/rotate-secret (o segredo antigo para de validar na hora) e pare as entregas com DELETE /webhooks/{id}.

Estes são os tipos de evento que um webhook pode assinar. Liste os que você quer ao se inscrever, ou omita o campo events para receber todos. O mesmo catálogo está em GET /webhooks/events, para descoberta programática.

Toda entrega traz um cabeçalho Axiospec-Signature no formato t=<unix-seconds>,v1=<hex>. Verifique-o antes de confiar em um payload: uma assinatura válida prova que a requisição veio do Axiospec e que o corpo não foi alterado no caminho.

Leia o cabeçalho Axiospec-Signature e separe-o na vírgula, na parte t= (um timestamp Unix em segundos) e na parte v1= (um HMAC em hexadecimal minúsculo). Recalcule o HMAC-SHA256, com a chave do segredo de assinatura do seu endpoint, sobre a string formada pelo timestamp, um ponto literal e o corpo bruto exato da requisição, ou seja f"{t}.{raw_body}". Compare seu digest hexadecimal com o valor v1 usando uma comparação de tempo constante, nunca uma igualdade comum.

Assine os bytes brutos exatamente como recebidos, antes de qualquer parsing ou reserialização de JSON, para que sua entrada bata com o que foi assinado. Recuse a entrega se os digests não baterem, ou se t tiver mais de uns cinco minutos, o que limita por quanto tempo uma requisição capturada poderia ser reenviada contra você.