Emitir uma chave de API

A chave de API é a porta pela qual um ERP, Kryia One, Sankhya, TOTVS, Omie, lança despesa direto no Domus, sem login. Ela não expira por ociosidade, não tem senha para trocar, e vale até ser revogada aqui.

Antes de começar

Emitir pede permissão para adicionar em Integrações; revogar pede excluir. Só o ADMIN as tem de fábrica: emitir credencial que escreve custo na conta é ato de administração.

1. Abra Configurações → Integrações

Cada chave mostra o prefixo (dk_…), o nome do sistema, o escopo, e quando foi usada pela última vez. É a informação que responde “posso revogar esta?”.

2. Emita

Clique em Emitir chave.

• Para qual sistema — “Sankhya produção”, “Kryia One”.
• O que ela pode fazer — o escopo, por recurso. Escopo diferente é outra chave: uma chave não se altera depois de emitida.

Clique em Emitir.

3. Copie agora

A chave aparece uma única vez. O Domus guarda só o resumo criptográfico dela, então reexibi-la é impossível por construção. Copie para o sistema de destino e clique em Já copiei. Se perder o texto, revogue esta e emita outra.

4. Revogue quando não usar mais

Revogar encerra a chave na hora. Ela fica na lista, riscada. Chave esquecida em servidor de terceiro é o jeito mais comum de uma credencial vazar; a coluna de último uso existe para isso.

O que acontece depois

O ERP envia as notas para o endereço de ingestão do Domus, com a chave no cabeçalho de autorização e uma chave de idempotência por documento. Cada nota aparece em Despesas na obra, como uma lançada pela tela. Quem configura o lado do ERP precisa dos dados abaixo:

POST https://<construtora>.domus.kryia.com.br/api/v1/ingest/despesas
Authorization: Bearer <a chave>
Idempotency-Key: <um por documento>

Ver lançar despesas.

Cada chave tem a própria cota de requisições por minuto, separada da cota por endereço que vale para o resto do Domus. Um ERP em laço consome a cota dele e nenhuma outra; um sistema que estoura a cota recebe 429 e tenta de novo mais tarde.

Problemas comuns

Fechei a caixa sem copiar. Revogue e emita outra. Não há como recuperar.

“Nenhuma chave emitida. Nenhum sistema externo consegue lançar no Domus.” É o estado inicial. Emita a primeira.

O ERP recebe erro de autorização. A chave foi revogada, ou o escopo não inclui o recurso. Emita outra com o escopo certo.