Chaves de API: criar, usar e revogar

A chave de API é a senha que um sistema de fora (a loja virtual, o ERP, uma planilha automatizada, um painel de indicadores) usa para ler e gravar dados no Codewo. Você cria a chave, escolhe o que ela pode fazer e, se quiser, de quais IPs ela pode ser usada. O texto completo da chave aparece uma única vez, na criação.

O que é

A API do Codewo fica no endereço /api/v1 do mesmo domínio em que você acessa o sistema. Cada chamada leva a chave no cabeçalho Authorization.

A chave age em nome da empresa, não de uma pessoa. Ela enxerga os dados da empresa inteira dentro das permissões marcadas, sem o recorte de cargo, equipe ou atendimento exclusivo por canal. Quando uma gravação precisa de um autor (um contato ou pedido criado pela API, por exemplo), o autor é quem criou a chave.
Onde fica: Configurações → Integrações → API & Chaves.
Depende do plano. Se API & Chaves não aparece em Integrações, o plano da sua empresa não inclui a API.
Permissões. Ver a tela pede Ver integrações. Criar, editar e revogar chaves pede Gerenciar integrações.

As 16 permissões da chave

No diálogo de criação, cada permissão aparece com o nome, o tipo (leitura, escrita ou remoção) e o código:

Grupo	Código	Nome na tela	Libera
Conversas	`conversations:read`	Ler conversas	Listar e abrir conversas
Conversas	`conversations:write`	Atualizar conversas	Hoje nenhuma chamada usa esta permissão
Mensagens	`messages:read`	Ler mensagens	Ler as mensagens de uma conversa
Mensagens	`messages:write`	Enviar mensagens	Enviar texto numa conversa que já existe
Contatos	`contacts:read`	Ler contatos	Listar, buscar e abrir contatos
Contatos	`contacts:write`	Criar/editar contatos	Criar e alterar contatos, inclusive o dono da carteira
Contatos	`contacts:delete`	Excluir contatos	Excluir contatos
Canais	`channels:read`	Ler canais	Listar os canais da empresa
Usuários	`users:read`	Ler usuários (agentes) da empresa	Listar a equipe (útil para saber quem envia a mensagem)
Templates	`templates:read`	Ler templates de mensagem (e HSM)	Ler os modelos de mensagem da equipe e os modelos aprovados do WhatsApp
Planos	`plans:read`	Ler catálogo de planos disponíveis ao tenant	Ler os planos disponíveis para a sua conta
Adicionais	`addons:read`	Ler catálogo de adicionais disponíveis	Ler os adicionais disponíveis para a sua conta
Catálogo	`products:read`	Ler o catálogo de produtos da empresa	Listar e abrir produtos
Catálogo	`products:write`	Criar e editar produtos	Cadastrar ou atualizar produto pelo SKU
Vendas	`orders:read`	Ler pedidos e vendas	Listar e abrir pedidos
Vendas	`orders:write`	Registrar vendas	Registrar pedidos

Como funciona

Criar uma chave

Exemplo: a loja virtual vai registrar no Codewo cada venda feita no site e consultar os contatos para não duplicar clientes.

Em Configurações → Integrações → API & Chaves, clique em Criar chave.
Nome: algo que diga quem usa a chave, como "Loja virtual - produção".
Descrição (opcional): onde a chave está instalada e quem responde por ela.
Permissões: marque só o necessário. Neste exemplo, Ler contatos, Ler o catálogo de produtos da empresa e Registrar vendas. Se marcar Excluir contatos, a tela avisa que a chave poderá remover dados e recomenda restringir IPs.
IPs permitidos (opcional): digite o IP do servidor da loja e clique em +. Aceita IP exato ou faixa (por exemplo, 10.0.0.0/8), até 50 itens. Lista vazia libera qualquer origem.
Expiração (opcional): data e hora em que a chave deixa de valer. Precisa estar no futuro.
Clique em Criar chave. Abre a janela Copie sua chave agora, com a chave completa (ela começa com cwo_live_). Clique em Copiar chave, guarde num cofre de senhas ou numa variável de ambiente e clique em Já guardei a chave. Depois disso, o Codewo não mostra a chave de novo.

Permissões, IPs e expiração só são definidos na criação. Depois, a tela deixa editar apenas nome e descrição. Para mudar o resto, crie uma chave nova e revogue a antiga.

Usar a chave

No topo da tela, o quadro URL base da API mostra o endereço completo, já com o domínio em que você acessa o Codewo, e tem o botão Copiar. Envie a chave em toda chamada:

curl https://SEU-ENDERECO/api/v1/me \
  -H "Authorization: Bearer cwo_live_xxxxxxxxxxxxxxxx"

Troque SEU-ENDERECO pelo domínio da URL base. A chamada /me serve para testar a chave: ela devolve a empresa, o nome e as permissões da chave, a validade e o limite por minuto.

Referência completa: na mesma tela, o link Reference interativa abre a lista de todas as chamadas, com parâmetros e exemplos de resposta. O link OpenAPI spec (YAML) baixa a especificação para importar em ferramentas como Postman ou Insomnia. Ao importar, confira o endereço do servidor e troque-o pela URL base da sua tela, se for diferente.
Listagens trazem até 100 itens por vez. A maioria pagina por cursor (cursor e limit); produtos e pedidos paginam por página (page e per_page).
Dinheiro de produtos e pedidos sai em centavos (total_cents, por exemplo).

Respostas de erro

Todo erro de acesso volta em JSON, no formato {"error": {"code": "...", "message": "..."}}:

Situação	HTTP	`code`
Sem o cabeçalho `Authorization`	401	`missing_api_key`
Chave errada ou inexistente	401	`invalid_api_key`
Chave revogada	401	`revoked_api_key`
Chave vencida	401	`expired_api_key`
IP fora da lista da chave	403	`ip_not_allowed`
Assinatura da empresa suspensa ou cancelada	402	`subscription_inactive`
Limite por minuto estourado	429	`rate_limited`
A chave não tem a permissão da chamada	403	`insufficient_scope` (informa a permissão que falta em `required_scope`)

Registro que não existe, ou que é de outra empresa, responde 404. Dado inválido responde 422, com os campos que falharam.

Limites por minuto

Por chave: o quadro Limites da tela mostra quantas requisições por minuto cada chave pode fazer.
Por empresa: existe também um teto maior para a empresa inteira, somando todas as chaves. Criar mais chaves não aumenta o volume total.
Toda chamada aceita pela chave traz na resposta os cabeçalhos X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset, do limite que está mais perto de acabar, e X-RateLimit-Scope diz qual é (key ou company).
Passou do limite: resposta 429, com retry_after (segundos para esperar) e o cabeçalho Retry-After.

Acompanhar o uso

Lista de chaves: nome, começo e fim da chave (o meio fica oculto), quantas permissões ela tem, total de requisições e o último uso. Chaves revogadas ou vencidas ficam no fim da lista, esmaecidas.
Uso da API: requisições por dia nos últimos 30 dias, com o total e a taxa de sucesso.
Logs: o ícone Ver logs de cada chave abre as últimas 100 requisições, com método, caminho, código de resposta, tempo, IP e o erro, quando houve. Dá para filtrar por 2xx, 4xx e 5xx. Registros com mais de 30 dias são apagados automaticamente.
Status da API: o quadro de links mostra se a API está operando normalmente.

Revogar

Clique no ícone de lixeira (Revogar chave) e confirme em Revogar chave. A partir desse momento, toda chamada com aquela chave recebe 401. Não dá para desfazer: a chave continua na lista, riscada, com os logs, mas não volta a funcionar.

Pegadinhas comuns

A chave completa aparece uma vez só. Não copiou? Crie outra e revogue a que ficou sem uso.
Chamada recusada na porta não aparece nos logs. Falta do cabeçalho Authorization, chave errada, revogada ou vencida, IP fora da lista e assinatura inativa são recusados antes de registrar. Se o sistema de fora diz que chamou e o log está vazio, confira a chave e o IP.
Faixa de IP só funciona em IPv4. Endereço IPv6 só é aceito se for exatamente igual ao da lista.
Criar contato pela API sempre cria. A chamada não procura por telefone nem e-mail antes. Reenviar o mesmo cadastro duplica o contato: consulte antes de criar. Produtos, ao contrário, são atualizados quando o SKU já existe, e pedidos enviados com external_id não se repetem.
Enviar mensagem exige quem envia. A chamada pede o sender_id de uma pessoa da equipe (liste com users:read).
O que a API não faz hoje. Não abre conversa nova nem envia modelo aprovado (HSM), só texto numa conversa que já existe. Não lê nem grava campos personalizados nem etiquetas do contato. Não edita nem cancela pedido e não tem chamadas de orçamento, negociação ou relatório.
Quem tem a chave vê tudo o que ela libera. Com messages:read, a chave lê as mensagens de todos os canais, inclusive dos que têm atendimento exclusivo.
Chave no código-fonte vaza. Nunca coloque a chave em repositório nem em código que roda no navegador do cliente.

Boas práticas

Uma chave por integração. "Loja virtual - produção", "Loja virtual - testes" e "Painel de indicadores" em chaves separadas: quando uma vaza ou quebra, só ela é revogada.
Permissão mínima. Marque só o que a integração usa. Leitura não precisa de escrita.
Restrinja IPs sempre que o sistema de fora tiver IP fixo, principalmente em chaves que gravam ou excluem.
Troque sem parar nada. Crie a chave nova, instale no sistema de fora, confira nos logs que ela está sendo usada e só então revogue a antiga.
Dê validade a chaves temporárias, como a de um fornecedor que vai fazer uma importação.
Revise o último uso. Chave sem uso há meses provavelmente pode ser revogada.
Respeite o 429. Espere o tempo de retry_after antes de tentar de novo, em vez de repetir em sequência.

Veja também

Começando com Webhooks: o Codewo avisando o seu sistema quando algo acontece.
Webhooks de saída: guia completo
Receber dados de outro sistema: outro sistema disparando uma automação.
Integrações externas