Integração

Aqui vivem as duas credenciais da conta e o webhook de alertas. A regra de ouro: API key (rk_…) autentica o que você chama no motor; secret de integração assina o que o motor chama em você (endpoint de preço, webhooks). Nunca confunda as duas.

Rota	O que faz
GET /v1/integration	Secret vigente, rotação em curso e webhook
POST /v1/integration/secret/rotate	Novo secret, com 24h de graça para o anterior
PUT /v1/integration/alert-webhook	Define (ou desliga) a URL de alertas
POST /v1/integration/alert-webhook/test	Entrega um evento de exemplo, assinado
POST /v1/integration/api-keys	Cria uma API key — o valor aparece uma vez
GET /v1/integration/api-keys	Lista as keys ativas, sem o valor
DELETE /v1/integration/api-keys/{apiKeyId}	Revoga imediatamente

Estado da integração

GET /v1/integration

Resposta 200:

Campo	Tipo	Descrição
secretLastFour	string	Últimos 4 caracteres do secret vigente — para conferir qual está em uso
previousSecretExpiresAt	datetime | null	Até quando o secret anterior ainda é aceito — null = nenhuma rotação em curso
alertWebhookUrl	string | null	URL que recebe alertas e eventos — null = desligado
gateways[]	array	Conexões ativas pelas quais o motor consegue emitir — ver abaixo

Cada elemento de gateways[]:

Campo	Tipo	Descrição
connectionId	string (uuid)	Id da conexão — é o gatewayConnectionId aceito na criação de assinatura
provider	string	Gateway (vindi, stripe, asaas…)
environment	string	sandbox ou production
issuableMethods	array de string	Métodos que esta conexão emite (card, pix, boleto)
maxCardInstallments	integer	Parcelamento máximo no cartão desta conexão

Com mais de uma conexão listada aqui, toda assinatura nova precisa escolher a sua via gatewayConnectionId. Conexão que não emite cobrança (ex.: gateway usado só pela Recuperação) não aparece na lista.

Rotacionar o secret

POST /v1/integration/secret/rotate

Gera um novo secret de integração. O novo assina na hora; o anterior segue aceito por 24 horas — rotação sem downtime: publique o novo no seu sistema dentro da janela e nenhuma verificação falha.

Resposta 200:

Campo	Tipo	Descrição
secret	string	O novo secret em claro — só aparece aqui. Guarde agora
previousSecretExpiresAt	datetime	Quando o secret anterior deixa de ser aceito

Configurar o webhook de alertas

PUT /v1/integration/alert-webhook

Para onde o motor avisa na hora: endpoint de preço falhando, fatura retida, cobrança recusada — o catálogo completo. Toda entrega sai assinada com o secret de integração (verificação).

Corpo:

Campo	Tipo	Obrigatório	Descrição
url	string | null	Sim	URL https do seu webhook — null desliga

Resposta 200: o estado da integração atualizado.

Testar o webhook de alertas

POST /v1/integration/alert-webhook/test

Envia um evento de exemplo, assinado, para o webhook cadastrado e devolve o resultado cru:

Campo	Tipo	Descrição
delivered	boolean	Se o seu endpoint aceitou (2xx)
responseStatus	integer | null	Status HTTP devolvido — null quando nem respondeu
responseBody	string | null	Corpo cru da resposta, truncado
latencyMs	integer	Tempo de resposta em milissegundos
error	string | null	Erro de rede/timeout, cru

Erros: 409 (nenhum webhook cadastrado).

Criar API key

POST /v1/integration/api-keys

Corpo:

Campo	Tipo	Obrigatório	Descrição
name	string	Sim	1–120 caracteres — um nome por ambiente (producao, staging) facilita revogar depois

Resposta 201:

Campo	Tipo	Descrição
id	string (uuid)	Identificador da chave — é o que se usa para revogar
name	string	Nome dado à chave
lastUsedAt	datetime | null	Último uso — null recém-criada
createdAt	datetime	Quando foi criada
plainKey	string	A chave rk_… em claro — mostrada UMA vez. Guarde agora

Listar API keys

GET /v1/integration/api-keys

Resposta 200: as chaves ativas, cada uma com id, name, lastUsedAt e createdAt — nunca o valor em claro. lastUsedAt é como você identifica uma key esquecida antes de revogar.

Revogar API key

DELETE /v1/integration/api-keys/{apiKeyId}

A chave para de autenticar imediatamente — não há período de graça (o mecanismo de graça existe só na rotação do secret). Revogar a única key da conta corta o seu próprio acesso via API: crie a substituta antes.

Resposta 200: a chave revogada (id, name, lastUsedAt, createdAt). Erros: 401 (chave não encontrada ou já revogada).