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, registe calibrações no registo com deteção de adulteração e leia os locais do seu espaço de trabalho e as normas de conformidade que selecionou.

É um contrato estável e selecionado, separado dos endpoints internos que as aplicações web e móvel usam. Assim a sua integração continua a funcionar à medida que o produto evolui. Todas as respostas são JSON.

Todos os endpoints vivem sob um único URL base. Todos os caminhos na referência abaixo são relativos a ele.

Autentique cada pedido com uma chave de API por espaço de trabalho. Um administrador do espaço de trabalho cria uma na aplicação em Definições e depois Chaves de API. As chaves são mostradas uma única vez, na criação, e têm o prefixo ctk_. Guarde a chave como um segredo e nunca a inclua em código do lado do cliente.

Envie a chave em cada pedido como token bearer:

Se preferir, também é aceite um cabeçalho X-API-Key padrão: X-API-Key: ctk_your_api_key. Um pedido sem chave devolve 401.

A API está disponível nos planos Professional e superiores. Uma chave que pertença a um espaço de trabalho no plano Free ou Starter recebe um 403 com o código API_ACCESS_TIER_REQUIRED. Faça o upgrade do espaço de trabalho para a ativar.

Cada chave é emitida com um âmbito. Uma chave de leitura pode listar e obter. Uma chave de escrita pode também criar instrumentos, atualizá-los e registar calibrações (escrita implica sempre leitura).

Uma chave só de leitura que tente uma escrita recebe um 403 com o código INSUFFICIENT_SCOPE, que indica o âmbito necessário. Emita chaves só de leitura para integrações de relatórios, para que nunca possam alterar um registo.

Os pedidos estão limitados a 120 por minuto, contados por chave de API e não por IP. Assim uma integração não esgota outra e várias chaves atrás da mesma rede de escritório não são limitadas em conjunto.

Cada resposta da API traz a janela atual em cabeçalhos, para que possa regular o ritmo sem adivinhar. X-RateLimit-Limit é o teto (120), X-RateLimit-Remaining é quantos pedidos restam na janela atual e X-RateLimit-Reset é o número de segundos até a janela reiniciar e Remaining voltar ao limite completo.

Exceder o limite devolve um 429 com o código RATE_LIMITED. No 429, um cabeçalho Retry-After (em segundos) diz-lhe exatamente quanto tempo esperar. Respeite-o e depois repita. Ler estes cabeçalhos em vez de fixar um atraso no código mantém-no rápido quando há margem e contido quando não há.

Para manter um sistema externo em dia sem reler tudo, obtenha apenas o que mudou desde a última execução. Cada coleção aceita um parâmetro updated_since (um carimbo temporal ISO-8601 em UTC) que devolve apenas os registos modificados nesse instante ou depois dele, e um parâmetro sort para os percorrer do mais antigo para o mais recente e avançar uma marca de água à medida que avança.

O feed de calibrações de todo o tenant, GET /calibrations, foi feito exatamente para isto: devolve todas as calibrações de todos os seus instrumentos num único fluxo paginado, por isso não precisa de iterar instrumento a instrumento. Ordene de forma ascendente por updated_at, percorra as páginas e guarde o created_at do último registo que viu. O registo é só de acréscimo, por isso um registo de calibração nunca muda depois de escrito e o seu created_at é a sua hora de última modificação. sort=updated_at corresponde a esse instante.

Na execução seguinte, passe esse valor guardado como updated_since. Sobreponha a fronteira em um ou dois segundos e elimine duplicados pelo id do registo, para se proteger de desvios de relógio. Guarde a marca de água só depois de ter processado a página de forma durável.

Os instrumentos suportam os mesmos parâmetros updated_since e sort (GET /instruments), filtrando pela hora de última modificação do instrumento. As linhas da lista não incluem um campo de carimbo temporal, por isso, para instrumentos, use como próximo updated_since a hora de relógio que capturou imediatamente antes do pedido. O GET /instruments/{id} de um único instrumento devolve created_at e updated_at, caso precise deles.

GET /instruments aceita filtros para que possa obter uma fatia precisa em vez de paginar todo o inventário. asset_tag e serial_number correspondem a um valor exato (útil para reconciliar um único instrumento com um registo do ERP). status filtra pelo estado do ciclo de vida, por exemplo active ou retired. site_id restringe a um local.

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

Registar uma calibração é a única escrita que nunca pode ser duplicada: o registo é só de acréscimo, por isso não há forma de anular um envio duplo. Por essa razão, POST /instruments/{id}/calibrations exige um cabeçalho Idempotency-Key (qualquer cadeia única que gere, por exemplo um UUID). É obrigatório, não opcional.

Se um pedido for interrompido e o repetir com a mesma chave, a API devolve o registo que já escreveu em vez de escrever um segundo. Uma chave em falta devolve um 400 com o código IDEMPOTENCY_KEY_REQUIRED. Gere uma chave nova por cada calibração que pretende registar.

Criar um instrumento (POST /instruments) também respeita um Idempotency-Key, mas aqui é opcional. Envie um e uma repetição com a mesma chave devolve o instrumento que a primeira chamada criou em vez de um duplicado, exatamente como no registo de calibração. A única diferença é que a chave não é obrigatória. Se preferir não gerir chaves nas criações, pode em vez disso eliminar duplicados 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 de fazer o POST.

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

Um certificado existe apenas para uma calibração aprovada e atual. Se o registo for anulado, substituído por uma entrada posterior ou por outro motivo não certificável, o pedido devolve um 404 com o código CERTIFICATE_UNAVAILABLE. Um id de calibração que não é seu, ou que não existe, devolve um 404 simples que nada revela sobre ele.

Quando um instrumento sai de serviço, retire-o com POST /instruments/{id}/retire (uma chamada de âmbito de escrita). É uma desativação suave: o estado do instrumento passa a retired e ele sai da lista ativa por defeito, mas nada é apagado e o seu histórico de calibração no registo fica totalmente intacto para auditoria. Não há eliminação definitiva na API.

A chamada devolve o instrumento atualizado. É idempotente: retirar um instrumento que já está retirado não faz nada e devolve o mesmo registo retirado, por isso repetir é sempre seguro. Retirar exige uma chave de gestor ou administrador. Uma chave só de leitura ou de técnico recebe um 403.

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

Todos os carimbos temporais que a API devolve são ISO-8601 em UTC, terminados em Z, por exemplo 2026-07-09T15:30:00Z. Envie os carimbos temporais da mesma forma. Não há respostas com desvio ou hora local para normalizar.

Um campo é uma data simples, não um carimbo temporal: 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, por isso uma data de vencimento é o dia de calendário em que vence aí, e o filtro next_due_before recebe uma data (YYYY-MM-DD) e não um carimbo temporal. Se os seus sistemas correm noutro fuso, compare pela data e não por um instante de meia-noite UTC.

Todos os erros, em todos os endpoints, têm a mesma forma JSON: um code legível por máquina, uma message legível por pessoas e, para alguns erros, um objeto details com os pormenores. Ramifique pelo code, nunca pelo texto da mensagem, que pode ser reescrito. O estado HTTP continua a ter significado (401 contra 403 contra 404), por isso use-o também.

Registar uma calibração também aplica os requisitos de campos das normas que o seu espaço de trabalho selecionou. Se um campo obrigatório estiver em branco, o pedido devolve um 422 com o código FIELD_REQUIREMENTS_UNMET e um array missing_fields, em que cada entrada indica o campo e qual a norma que o exige, para que possa pedir exatamente o que falta.

Em vez de consultar a API periodicamente para descobrir o que mudou, subscreva um endpoint de webhook uma vez e o Axiospec entrega cada evento no seu URL à medida que acontece. Tem menor latência e muito menos tráfego desperdiçado do que reler coleções que já viu, e nunca perde uma alteração entre duas consultas.

Subscreva com POST /webhooks, passando um 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, por isso copie-o diretamente para o seu cofre de segredos. Gerir webhooks exige uma chave de âmbito de escrita de administrador ou gestor, porque o endpoint recebe os dados de calibração e de instrumentos do seu espaço de trabalho.

Cada evento é entregue como um HTTP POST cujo corpo JSON é um envelope fixo: { "id", "type", "created_at", "data" }. O id é o id estável do evento, enviado de novo como cabeçalho Axiospec-Event-Id, juntamente com Axiospec-Event-Type, Axiospec-Webhook-Id e Axiospec-Delivery-Attempt. A entrega é pelo menos uma vez, por isso o mesmo evento pode chegar mais do que uma vez (por exemplo após uma repetição). Elimine duplicados pelo id do envelope.

Uma entrega conta como falhada em qualquer resposta que não seja 2xx, e isso inclui um redirecionamento 3xx: um redirecionamento podia apontar para um endereço interno, por isso nunca é seguido. Erros de transporte e tempos de espera esgotados também contam como falhas. As entregas falhadas são repetidas com recuo exponencial ao longo de cerca de três dias, após o que a entrega é marcada como esgotada. Um endpoint cujas entregas recentes se esgotem todas é desativado automaticamente, para que um URL morto ou hostil deixe de consumir capacidade. Os endpoints têm de ser HTTPS, e um URL que resolva para um endereço privado ou interno é rejeitado na subscrição.

Inspecione o que foi enviado com GET /webhooks/{id}/deliveries, que pagina o histórico de entregas de um endpoint e aceita um filtro status (pending, failed, succeeded, exhausted). Para reenviar uma entrega, POST /webhooks/{id}/deliveries/{delivery_id}/retry: repõe essa entrega em pending e com vencimento imediato, para que o próximo despacho a reenvie com um novo horizonte de repetições. Rode o segredo de um endpoint com POST /webhooks/{id}/rotate-secret (o segredo antigo deixa de verificar de imediato) e pare as entregas com DELETE /webhooks/{id}.

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

Cada entrega traz um cabeçalho Axiospec-Signature na forma t=<unix-seconds>,v1=<hex>. Verifique-o antes de confiar num payload: uma assinatura válida prova que o pedido veio do Axiospec e que o corpo não foi alterado em trânsito.

Leia o cabeçalho Axiospec-Signature e divida-o na vírgula na sua parte t= (um carimbo temporal Unix em segundos) e na sua parte v1= (um HMAC hexadecimal em minúsculas). Recalcule o HMAC-SHA256, com o segredo de assinatura do seu endpoint como chave, sobre a cadeia formada pelo carimbo temporal, um ponto literal e o corpo bruto exato do pedido, isto é, f"{t}.{raw_body}". Compare o seu resumo hexadecimal com o valor v1 usando uma comparação em tempo constante, nunca uma verificação de igualdade comum.

Assine os bytes brutos exatamente como recebidos, antes de qualquer análise ou reserialização JSON, para que a sua entrada corresponda ao que foi assinado. Rejeite a entrega se os resumos não coincidirem, ou se t tiver mais de cerca de cinco minutos, o que limita durante quanto tempo um pedido capturado poderia ser reproduzido contra si.