Aplicativos OAuth e API REST da Klyro
Cadastre integrações, proteja credenciais e use a API /v1 (auth, recursos, verbos HTTP, contacts/conversations POST+PATCH, organizations, tickets, opportunities, outbound messages, campaigns, marketing, channels, templates, boards, motivos de perda, erros, cobrança).
A aba Aplicativos em Configurações da empresa cria credenciais OAuth (client credentials) para sistemas que usam a API REST Klyro em https://app.klyro.group/v1.
Documentação interativa no produto: /api-docs. Contrato máquina: GET /v1/openapi (OpenAPI 3.1).
Campos da aplicação
- Nome: identificação obrigatória da integração.
- Descrição: finalidade e responsável pelo uso.
- URL de callback: endereço autorizado para o retorno OAuth; em produção use HTTPS.
localhosté aceito em desenvolvimento. - Client ID: identificador público (
ka_…). - Client secret: segredo usado na troca por token (
sk_…). Mostre uma vez ao criar ou regenerar. - Permissões (scopes): o que a chave pode chamar. Sem permissão, a API responde
403 scope_not_granted.
Ações na tela
- Criar, editar e excluir aplicativos.
- Copiar credenciais; regenerar o client secret (invalida o anterior).
- Conceder permissões por chave.
- Abrir a Documentação da API e acompanhar uso/créditos no painel da tela.
Segurança: o client secret fica só no servidor da integração. Regenerá-lo exige atualizar o sistema cliente. Nunca embuta o secret em JavaScript de navegador.
Autenticação (client credentials)
- Crie o aplicativo e copie
client_id+client_secret. - Troque as credenciais por um bearer token via
POST …/functions/v1/app-oauth(único host diferente da base/v1). - Chame
https://app.klyro.group/v1/…comAuthorization: Bearer kat_live_….
O token é opaco (não é JWT). Não tente decodificá-lo. Ele autentica a empresa inteira — use apenas servidor-a-servidor. A API não envia CORS; chamadas do browser de outra origem falham.
Permissões disponíveis
contacts:read/contacts:create/contacts:updateconversations:read/conversations:create/conversations:updatemessages:read/messages:sendagents:readorganizations:read(expõefederal_tax_id_number) /organizations:create/organizations:updatetickets:read(expõesubject/message) /tickets:create/tickets:updateopportunities:read(expõenotese valores comerciais) /opportunities:create/opportunities:updatemarketing:read/marketing:publishcampaigns:read/campaigns:create/campaigns:updatecampaign_recipients:read/campaign_recipients:createchannels:read(expõeidentifier— telefone ou e-mail do canal)whatsapp:read(lista os templates de WhatsApp: id, nome, idioma, categoria e status)
Todo scope concedível do catálogo tem rota pública correspondente; permissões sem rota ficam ocultas em Aplicativos e são rejeitadas no autoatendimento. Todos os scopes acima podem ser concedidos por autoatendimento na tela de Aplicativos.
Recursos da API v1
GET /v1/contacts,GET /v1/contacts/{id},POST /v1/contacts(exigeIdempotency-Key),PATCH /v1/contacts/{id}— mesma whitelist de escrita do POST; corpo vazio é no-opGET /v1/conversations,GET /v1/conversations/{id},POST /v1/conversations(exigeIdempotency-Key; reutiliza 200 / cria 201),PATCH /v1/conversations/{id}— POST exigecontact_id+channel_connection_id(chn_…, deGET /v1/channels, status connected);assigned_to(agt_…) opcional; workflows de input do canal não disparam no POST; PATCH: assign (agt_…ou null),major_status(in_progress|completed|archived);outcome_category_idsó com completed; corpo vazio é no-opGET /v1/conversations/{id}/messages(sem notas internas da equipe)GET /v1/agents,GET /v1/agents/{id}— equipe (staff), não AI AgentsGET /v1/organizations,GET /v1/organizations/{id},POST /v1/organizations(exigeIdempotency-Key),PATCH /v1/organizations/{id}— CRM "empresas", referenciadas porcontacts.contacts_organization_idGET /v1/tickets,GET /v1/tickets/{id},POST /v1/tickets(exigeIdempotency-Key),PATCH /v1/tickets/{id}— chamados de suporte; o PATCH só alterastatus/tagsGET /v1/opportunities,GET /v1/opportunities/{id},POST /v1/opportunities(exigeIdempotency-Key),PATCH /v1/opportunities/{id}— CRM oportunidades; POST exigeboard_id(brd_…),phase_id(bph_…) econtact_id(con_…); PATCH move (phase_id), win (action: win) ou lose (action: lose+loss_reason_idlrs_…)POST /v1/whatsapp/messages— template AUTHENTICATION aprovado (OTP/notificação); exigeIdempotency-KeyPOST /v1/outbound/messages— envia mensagem porchannel_id(telegram,zernio,sms,email); entrega assíncrona (202); exigeIdempotency-KeyGET /v1/campaigns,GET /v1/campaigns/{id},POST /v1/campaigns(exigeIdempotency-Key),PATCH /v1/campaigns/{id}— campanhas de mensagens em massa somente emzernio(WhatsApp Oficial) esms; outro canal responde400 validation_errorcom o códigocampaign_channel_not_supportedemchannel_id; POST exigename,channel_idechannel_connection_id, maismessage_templatesemsmsouwhatsapp_template({ template_id, variable_mappings }, template aprovado da mesma conexão) emzernio; cada variação de mensagem emmessage_templatesprecisa ter texto além de espaços e variáveis — variação vazia responde400 validation_errorcom o códigoinvalid_valueemmessage_templates(POST e PATCH); PATCH só gravaname/message_templatescom statusdraft(e recusamessage_templatesem campanhaszernio), estatussegue as transiçõesdraft→running→paused→runninge→canceled(completedsó pelo worker de disparo); campanhas antigas em canal removido só podem ser pausadas ou canceladasGET /v1/campaigns/{id}/recipients,POST /v1/campaigns/{id}/recipients(exigeIdempotency-Key) — até 500 destinatários por requisição; pares(campaign_id, destination)duplicados são ignorados e reportados emmeta; somente com campanhadraftoupausedem canal suportado (campaign_channel_not_supportednos demais)GET /v1/marketing/social-publications,GET /v1/marketing/social-publications/{id}—marketing:readPOST /v1/marketing/social-publications— mídia via URL pública do Google Drive; exigeIdempotency-Keyemarketing:publishPATCH /v1/marketing/social-publications/{id}— só com statusscheduled(cancelar / remarcação / caption+hashtags; mídia imutável)GET /v1/channels— todos os canais conectados (status=connected), comusable_for(conversations,campaigns,marketing_publications) dizendo quais chamadas aceitam o idchn_…comochannel_connection_id; filtros?channel=e?usable_for=(marketing_publicationsdevolve os canais com o toggle "permitir marketing" ativo, Instagram e Facebook).POST /v1/outbound/messagesnão recebechannel_connection_idGET /v1/whatsapp/templates— templates de WhatsApp da empresa, em qualquer status, com o idtpl_…detemplate_ideusable_for(whatsapp_messages: APPROVED + AUTHENTICATION;campaigns: APPROVED); filtros?usable_for=e?status=GET /v1/boards— quadros ativos com suas fases (brd_…,bph_…) paraboard_idephase_iddePOST /v1/opportunitiesGET /v1/loss-reasons— motivos de perda ativos (lrs_…) paraloss_reason_id;justification_requiredindica quando o PATCH também exigeloss_justificationGET /v1/openapi— especificação OpenAPI pública
Agents ≠ AI Agents: /v1/agents lista pessoas do time (nome, e-mail, papel, status). Bots de IA configuráveis são outra superfície do produto e não são este endpoint.
Em organizations, apenas description é obrigatório e federal_tax_id_number precisa ser único por empresa quando informado (409 organizations_tax_id_duplicate). Em tickets, apenas subject é obrigatório no POST; type_id 2 (externo) exige contact_id; tags precisa corresponder exatamente a uma tag já existente da empresa — nenhuma tag é criada por esta API. Em opportunities, win exige pelo menos um item de produto na oportunidade (via UI do CRM); lose exige loss_reason_id válido. Erros de escrita de marketing incluem error.retryable.
Convenções do contrato
- Verbos HTTP: a API v1 expõe apenas GET, POST e PATCH. PATCH é o verbo de atualização — mudanças parciais contra whitelist explícita por recurso; POST exige
Idempotency-Keynas escritas. PUT e DELETE não fazem parte desta versão — não há substituição total nem remoção definitiva; arquivar/cancelar/desativar usa PATCH nos campos de status documentados. Métodos não suportados →405 method_not_allowed. - snake_case nos campos JSON.
- IDs com prefixo:
con_contato,cnv_conversa,agt_agente,cmp_empresa,org_organização,tkt_chamado,opp_oportunidade,brd_board,bph_fase,lrs_motivo de perda,mkt_publicação de marketing,cam_campanha,crc_destinatário de campanha,chn_canal conectado (ochannel_connection_id),tpl_template de WhatsApp (otemplate_id). Todo id enviado usa a forma com prefixo; UUID cru é recusado cominvalid_id. - Paginação por cursor (
?cursor=/meta.next_cursor) — sem offset. ?include=totalparameta.total(exato; omitido por padrão).?fields=,?updated_since=e filtros por igualdade por recurso.- Header opcional
Klyro-Version: YYYY-MM-DD. - Erros:
{ error: { type, code, message, request_id, doc_url } }— trate pelocode. Em escritas de marketing,retryabletambém pode estar presente.
Cobrança por operação
Usar a API não gasta créditos de IA (créditos de IA e uso de API são medidores separados) e a maior parte das chamadas não custa nada. Duas coisas controlam o seu uso: dois limites do plano (explicados abaixo) e, só em envios de SMS, um saldo que é gasto a cada mensagem enviada. Os números de cada plano mudam de plano para plano: veja a tabela em https://app.klyro.group/api-docs#billing e o quanto você já usou em Configurações da empresa > Aplicativos > Consumo da API.
1. Os dois limites do plano
- Limite de requisições por minuto. Vale para cada aplicativo e para cada grupo de recursos (contacts, conversations, envio de mensagens e assim por diante), separadamente, e conta toda chamada, inclusive leituras (GET), numa janela de 1 minuto. Ao passar, a API responde
429 rate_limit_exceededcom o cabeçalhoRetry-After(segundos de espera). A requisição não foi processada, então é seguro enviá-la de novo depois de esperar. - Franquia mensal de escrita. Conta os
POSTePATCHde toda a empresa (todos os aplicativos somados) no mês civil em UTC. Leituras (GET) não contam. Entram na conta os POST/PATCH respondidos com sucesso (2xx) e também os recusados depois que o token foi aceito (4xx, por exemplo erro de validação); respostas de erro do servidor (5xx) e o reenvio de uma mesmaIdempotency-Keynão contam de novo. O consumo é consolidado de hora em hora: o painel pode mostrar o valor com até 3 horas de atraso, e o bloqueio pode começar um pouco depois de a franquia ser atingida. Plano sem teto mensal não é medido.
Quando a franquia mensal de escrita acaba, todo POST/PATCH responde 403 plan_quota_exceeded até a franquia recomeçar no primeiro dia do mês seguinte (UTC); o Retry-After informa os segundos até lá. As leituras continuam funcionando. Para escrever antes, é preciso um plano com franquia maior.
2. O que gasta saldo
| Operação | Carteira / cobrança |
|---|---|
Leituras bem-sucedidas (GET em contacts, conversations, messages, agents, organizations, tickets, opportunities, campaigns, channels, boards, loss-reasons, whatsapp/templates) | Nenhuma. Só o limite por minuto. |
POST / PATCH em contacts, conversations, organizations, tickets, opportunities, campaigns e marketing | Nenhuma carteira. Contam no limite por minuto e na franquia mensal de escrita. |
POST /v1/whatsapp/messages (template de autenticação) | Nenhuma cobrança da Klyro (o WhatsApp é cobrado pela Meta). Conta no limite por minuto e na franquia mensal de escrita. |
POST /v1/outbound/messages com channel_id telegram ou zernio | Nenhuma cobrança da Klyro. Conta no limite por minuto e na franquia mensal de escrita. |
POST /v1/outbound/messages com channel_id sms, pelo número da Klyro (destinos no Brasil) | Segmentos de SMS: primeiro a franquia mensal de SMS do plano, depois o saldo pré-pago. Gasta 1 por segmento de SMS, no momento do envio real. Aceitar a requisição não debita nada. SMS de campanha pelo número da Klyro segue a mesma regra. Um boost ou pacote comprado soma ao saldo pré-pago, que não expira. |
POST /v1/outbound/messages com channel_id sms, pela sua própria conta de SMS | Nenhuma cobrança da Klyro (o provedor cobra você). Conta no limite por minuto e na franquia mensal de escrita. |
| Qualquer requisição recusada (4xx) | Nenhum saldo é cobrado. Um POST/PATCH rejeitado depois que o token é aceito (por exemplo, erro de validação) ainda conta na franquia mensal de escrita (item 1). |
3. O que acontece quando algo falta
- Sem segmentos de SMS (franquia do plano e saldo pré-pago zerados), num SMS pelo número da Klyro:
402 insufficient_ops_credits, antes de a mensagem entrar na fila (o nome do código chama os segmentos de SMS de "ops credits"). Se o saldo acabar depois que a requisição foi aceita, a mensagem fica com falha de entrega e não é enviada; acompanhe emGET /v1/conversations/{id}/messages. Destino fora do Brasil:422 sms_destination_not_supported. Só os SMS são afetados; as demais chamadas seguem normais. - Empresa suspensa (fim do teste ou da carência, assinatura não paga, cancelada ou incompleta): toda chamada
/v1, inclusive leituras, responde402 company_suspended. Isso é verificado antes do plano, das permissões e dos limites. Regularize a cobrança para restaurar o acesso. - Limite por minuto atingido:
429 rate_limit_exceeded(veja o item 1). - Franquia mensal de escrita esgotada:
403 plan_quota_exceeded(veja o item 1). - Plano sem acesso à API:
403 api_not_included_in_planem toda chamada.
4. Exemplo
Uma empresa tem um plano com franquia de escrita de 1.000 por mês (números só de exemplo; os do seu plano estão em https://app.klyro.group/api-docs#billing). Em um mês, o sistema dela:
- faz 5.000 consultas
GET /v1/contacts: não gastam franquia nem saldo (só entram no limite por minuto); - cria 800 contatos com
POST: usam 800 da franquia de escrita, sem saldo nenhum; - envia 150 SMS pelo número da Klyro, cada um com 1 segmento: usam 150 segmentos de SMS e também 150 da franquia de escrita (a chamada é um POST). Total da franquia de escrita usada: 950;
- manda 50
POSTcom um campo inválido: recebem400, não gastam saldo, mas somam 50 na franquia de escrita (agora 1.000, a franquia inteira).
A partir daí, o próximo POST ou PATCH volta 403 plan_quota_exceeded até o dia 1 do mês seguinte (UTC), mas os GET continuam funcionando.
Checklist rápido
- Plano com API habilitada? Confira o aviso na aba Aplicativos.
- Secret só no backend; scopes mínimos necessários.
- Primeira chamada: token em app-oauth →
GET /v1/contacts?limit=1. - Detalhes e exemplos curl: /api-docs.