Registro de Integrador
Registre sua aplicação (CRM, help desk, sistema de tickets) como integrador para receber credenciais de API.
Endpoint de Registro
cURL
curl -X POST https://api.ixblix.app/api/integrators/register \
-H "Content-Type: application/json" \
-d '{
"name": "My CRM Platform",
"hostname": "mycrm.example.com",
"callbackUrl": "https://mycrm.example.com/ixblix/callback"
}'Campos da Requisição
| Campo | Obrigatório | Descrição |
|---|---|---|
name | Sim | Nome de exibição do seu integrador. |
hostname | Sim | Hostname único para este integrador. Deve ser único entre todos os integradores. |
callbackUrl | Sim | URL para onde o ixblix envia as credenciais para verificação. |
force | Não | Se true, permite substituir um registro de hostname já verificado. Padrão: false. |
subscriptionId | Não | Identificador de assinatura no formato {paymentProvider}:{id}. A parte id é opaca para a API e interpretada internamente pelo provedor de pagamento. Obrigatório quando o provedor de pagamento atribuído precisa de uma referência de assinatura. |
Fluxo de Verificação via Callback
O registro acontece em três fases:
- Você chama
POST /api/integrators/register com seus dados. - O ixblix envia um desafio para seu
callbackUrl:
Payload do desafio {
"challenge": "mycrm.example.com"
}
Seu endpoint deve responder com 200 OK e o payload de registro exato que você enviou na fase 1.
- O ixblix envia suas credenciais para o mesmo
callbackUrl:
Payload de credenciais {
"event": "INTEGRATOR_CREDENTIALS",
"integratorId": "int_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"accessToken": "ixblix_integrator_token_xxxxxxxxxxxx",
"timestamp": "2026-01-15T10:30:00.000Z"
}
Seu endpoint deve ecoar o payload de credenciais de volta com 200 OK.
Armazene as credenciais com segurança — elas são usadas em todas as chamadas de API subsequentes.
Usando as Credenciais
Use as credenciais do integrador como HTTP Basic Auth:
cURL curl https://api.ixblix.app/api/plans \
-u "int_a1b2c3d4-...:ixblix_integrator_token_xxxx"
Exemplo de Handler
Handler Express import express from 'express';
const app = express();
app.use(express.json());
// Payload de registro enviado na fase 1
const registrationPayload = {
name: "My CRM Platform",
hostname: "mycrm.example.com",
callbackUrl: "https://mycrm.example.com/ixblix/callback",
};
app.post('/ixblix/callback', async (req, res) => {
// Fase 2: responde ao desafio com o payload de registro original
if (req.body?.challenge) {
return res.status(200).json(registrationPayload);
}
// Fase 3: armazena as credenciais e as ecoa de volta
if (req.body?.event === "INTEGRATOR_CREDENTIALS") {
const { integratorId, accessToken } = req.body;
await saveIntegratorCredentials({ integratorId, accessToken });
return res.status(200).json(req.body);
}
res.status(200).json({ received: true });
});