API de Entrada da Agencia
Provisione sub-contas a partir do seu proprio sistema. Crie um cliente, altere quais canais ele pode usar e remova-o — sem abrir o painel de agencia da GetRaze.
Esta API e para agencias whitelabel. Cada agencia tem o seu endpoint e os seus tokens.
Diferente do resto desta referencia
A API de Entrada da Agencia nao usa X-API-Key nem a base https://app.getraze.com/external/v1. Ela tem URL base propria, token Bearer proprio e escopos de permissao proprios, descritos abaixo.
URL Base
https://api.getraze.co/api/webhooks/agency/<agency_key>O agency_key identifica a sua agencia. Ele e publico — nao e segredo — e nunca muda, entao uma integracao publicada hoje continua funcionando depois que voce renomear a agencia ou trocar o subdominio.
Encontre o seu endpoint e gerencie os seus tokens no painel da agencia, em API & Webhooks.
Autenticacao
Envie o token no cabecalho Authorization. Nunca coloque na URL — URLs acabam em log de proxy e CDN.
Authorization: Bearer raz_ag_live_xxxxxxxxxxxxxxxxUm token so funciona no endpoint da agencia dona dele. Usa-lo na URL de outra agencia devolve 401.
Escopos
Cada token carrega um conjunto de escopos. Chamar uma operacao sem o escopo dela devolve 403 INVALID_SCOPE.
| Escopo | Permite | Concedido por padrao |
|---|---|---|
sub_account.create | Criar sub-contas | Sim |
sub_account.channels | Alterar cotas de canais | Sim |
sub_account.delete | Excluir sub-contas | Sim |
sub_account.credentials | Receber a senha temporaria do admin na resposta | Nao |
Conceda sub_account.credentials apenas se o seu sistema realmente precisar da senha. Sem ele, o novo admin recebe um e-mail de boas-vindas com o acesso.
Idempotencia
Envie um cabecalho Idempotency-Key unico em toda escrita. Se a mesma chave chegar duas vezes para a mesma agencia, devolvemos o resultado da primeira execucao em vez de rodar a operacao de novo.
Idempotency-Key: 8f14e45f-ea4d-4a2c-9f34-1c7b0a2e5d31Sem a chave, cada chamada e uma operacao nova — repetir uma requisicao que deu timeout poderia criar uma segunda sub-conta.
Uma chamada repetida responde com replayed: true:
{
"ok": true,
"replayed": true,
"event_id": "3f7b1c2e-9a44-4d1b-8f2e-6c5a1b0d9e83",
"data": { "id": "a1b2c3d4-5678-4e9f-a0b1-c2d3e4f5a6b7" }
}TIP
Uma repeticao devolve o resultado gravado. A senha temporaria do admin nunca e armazenada, entao ela nao aparece numa repeticao — apenas na primeira resposta.
Identificando uma sub-conta
As rotas que agem sobre uma sub-conta existente aceitam duas formas:
| Forma | Exemplo | Observacao |
|---|---|---|
| Nosso UUID | a1b2c3d4-5678-4e9f-a0b1-c2d3e4f5a6b7 | Devolvido na criacao |
| Seu proprio ID | ext:cliente-42 | Exige external_ref enviado na criacao |
O ext: permite que o seu CRM continue usando o identificador dele. O external_ref e unico por agencia entre as sub-contas vivas — excluir uma libera a referencia para reuso.
Canais
As cotas de canal sao expressas num objeto simples:
{ "linkedin": 2, "whatsapp": 1 }| Canal | Significado |
|---|---|
linkedin | Contas de LinkedIn que o cliente pode conectar |
whatsapp | Numeros de WhatsApp |
instagram | Contas de Instagram |
email_marketing | Dominios de envio de e-mail |
Os valores sao inteiros de 0 a 100.
O objeto e declarativo
channels descreve o estado final, nao um delta. Um canal omitido vai a zero. Para manter o WhatsApp enquanto aumenta o LinkedIn, envie os dois.
Adicionar canais cobraveis cobra da sua agencia na hora, no cartao cadastrado, pro-rata ate o fim do ciclo atual. Remover nao gera credito.
Formato da resposta
Toda resposta carrega ok e, nas escritas, o event_id da chamada registrada.
Sucesso
{
"ok": true,
"event_id": "3f7b1c2e-9a44-4d1b-8f2e-6c5a1b0d9e83",
"data": { }
}Erro
{
"ok": false,
"code": "EMAIL_ALREADY_REGISTERED",
"message": "Este email ja esta cadastrado em outra conta.",
"event_id": "3f7b1c2e-9a44-4d1b-8f2e-6c5a1b0d9e83"
}Use o event_id para consultar a chamada depois — veja Consultar um evento — ou para encontra-la na aba Eventos do painel da agencia.
Retentativas
Uma chamada que falha por motivo transitorio (timeout de banco ou do gateway de pagamento) e reprocessada automaticamente em segundo plano, ate cinco tentativas com backoff exponencial. Essas respondem 500 INTERNAL e ficam visiveis como pending ate se resolverem.
Erros de negocio — e-mail duplicado, cartao recusado, campo faltando — nao sao reprocessados. Corrija a causa e faca uma chamada nova com uma Idempotency-Key nova, ou clique em Reprocessar no evento dentro do painel da agencia.
Limites de uso
| Limite | Escopo | Resposta |
|---|---|---|
| 300 requisicoes/minuto | Por endereco IP | 429 RATE_LIMIT_IP |
| 60 requisicoes/minuto | Por token | 429 RATE_LIMIT_API |
| 5 sub-contas/hora | Por agencia | 429 RATE_LIMIT_SUBACCOUNT_CREATE |
O corpo da requisicao e limitado a 64 KB.
Tokens podem, opcionalmente, ser restritos a uma lista de IPs. Chamadas de qualquer outro lugar devolvem 403 IP_NOT_ALLOWED.
Usando ferramentas no-code
Make, n8n, Zapier e similares muitas vezes nao conseguem enviar DELETE nem PUT com corpo. Toda operacao tem um atalho em POST:
| Operacao | Forma canonica | Atalho POST |
|---|---|---|
| Alterar canais | PUT /sub-accounts/:ref/channels | POST /sub-accounts/:ref/channels |
| Excluir sub-conta | DELETE /sub-accounts/:ref | POST /sub-accounts/:ref/delete |
As duas formas se comportam igual e exigem o mesmo escopo.
Erros
| Status | Codigo | Descricao |
|---|---|---|
| 400 | MISSING_FIELDS | Um campo obrigatorio esta ausente |
| 400 | INVALID_CHANNELS | Canal desconhecido, ou valor fora de 0–100 |
| 400 | INVALID_EXTERNAL_REF | external_ref nao e string de ate 120 caracteres |
| 400 | CONFIRMATION_REQUIRED | Exclusao sem "confirm": true |
| 401 | UNAUTHORIZED | Token ausente, desconhecido, revogado ou de outra agencia |
| 402 | NO_PAYMENT_METHOD | A agencia nao tem cartao cadastrado |
| 402 | SEAT_CHARGE_FAILED | A cobranca pro-rata foi recusada |
| 403 | INVALID_SCOPE | O token nao tem o escopo desta operacao |
| 403 | IP_NOT_ALLOWED | IP de origem nao esta na allowlist do token |
| 403 | AGENCY_NOT_APPROVED | A agencia ainda nao foi aprovada |
| 403 | AGENCY_SUSPENDED | A agencia esta suspensa por inadimplencia |
| 403 | AGENCY_CANCELLED | A agencia foi cancelada |
| 403 | AGENCY_INACTIVE | A conta nao e uma agencia ativa |
| 403 | SUB_ACCOUNT_FORBIDDEN | A sub-conta pertence a outra agencia |
| 404 | SUB_ACCOUNT_NOT_FOUND | Nenhuma sub-conta viva para essa referencia |
| 404 | EVENT_NOT_FOUND | Nenhum evento com esse id para esta agencia |
| 409 | EMAIL_ALREADY_REGISTERED | O e-mail do admin ja esta em uso |
| 409 | EXTERNAL_REF_ALREADY_USED | Outra sub-conta viva ja usa esse external_ref |
| 409 | IN_PROGRESS | Uma chamada com esta Idempotency-Key ainda esta rodando |
| 429 | RATE_LIMIT_IP | Requisicoes demais deste IP |
| 429 | RATE_LIMIT_API | Requisicoes demais para este token |
| 429 | RATE_LIMIT_SUBACCOUNT_CREATE | Mais de 5 sub-contas em uma hora |
| 500 | INTERNAL | Falha transitoria; a chamada sera reprocessada automaticamente |