Várias organizações (agência)

​

Como o acesso funciona

• A unidade de isolamento é a organização. Número, templates, contatos, conversas, opt-outs, campanhas, automações, webhook, base de conhecimento do Brain, carteira e faturamento pertencem a ela.
• Cada usuário (e-mail) pertence a uma organização por vez.
• A chave de API pertence ao usuário que a criou e age na organização desse usuário.
• Não existe troca de organização por API: cada chave age em uma organização só.

​

Antes de começar

• Um e-mail da agência exclusivo para cada cliente.
• Um cofre de segredos para guardar uma chave de API por cliente.
• O CLI instalado, se você for operar pelo terminal.

​

Passo a passo

curl -X POST https://api.ararahq.com/v1/team/invitations \
  -H "Authorization: Bearer $ARARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "emails": ["operacao+clientex@suaagencia.com"], "role": "ADMIN" }'

// clients.ts
import { NodeSDK, type SendMessageRequest } from '@ararahq/sdk';

const clients = new Map<string, NodeSDK>([
  ['cliente-x', new NodeSDK({ apiKey: process.env.ARARA_KEY_CLIENTE_X! })],
  ['cliente-y', new NodeSDK({ apiKey: process.env.ARARA_KEY_CLIENTE_Y! })],
]);

export async function sendFor(clientId: string, payload: SendMessageRequest, idempotencyKey: string) {
  const sdk = clients.get(clientId);
  if (!sdk) throw new Error(`Cliente ${clientId} não configurado`);
  return sdk.messages.send(payload, { idempotencyKey });
}

arara profile add cliente-x
arara login --profile cliente-x

arara profile add cliente-y
arara login --profile cliente-y

arara profile list
arara profile switch cliente-x
arara send --to +5511999999999 --template ola_mundo --vars "João"

# Ou sem trocar o profile ativo
arara send --profile cliente-y --to +5511999999999 --template ola_mundo --vars "Maria"

​

Armadilhas

• arara org use não troca a credencial. arara org list e arara org use existem, mas a chave continua agindo na organização do usuário. Para trocar de cliente, troque de profile.
• Não há visão agregada. Consulte cada organização com a chave dela (GET /v1/campaigns, GET /v1/contacts/stats, GET /v1/recovery/stats) e consolide do seu lado.
• Cada cliente paga o próprio consumo. Carteira e assinatura são da organização. A cobrança da agência pelo serviço é feita por fora da Arara. Para revenda sob a sua marca, fale com contato@ararahq.com.

​

Auditoria e revogação

• Chave vazou: revogue só ela, em API Keys ou com DELETE /v1/api-keys/{id} pela sessão do painel. As outras organizações não são afetadas.
• GET /v1/api-keys/{id}/events: histórico da chave (criada, revogada, rotacionada, mudança de escopo ou IP), com actorUserId e data.
• GET /v1/api-keys/{id}/stats: volume de chamadas e taxa de sucesso em 7 e 30 dias.
• GET /v1/team/audit-log: eventos do time (convites, mudanças de papel, remoções).

​

Quando o cliente sai

1. O cliente remove o usuário da agência em Time (ou DELETE /v1/team/members/{id}). A remoção revoga todas as chaves de API desse usuário.
2. Apague do seu lado a chave e o profile do CLI (arara profile remove cliente-x).
3. Se o cliente pedir, exporte os contatos (GET /v1/contacts/export) antes da saída.

​

Próximos passos