API Keys de parceiros: credenciais e callbacks

Crie credenciais no painel, proteja API Key e Webhook Secret e configure callbacks opcionais com HTTPS e circuit breaker.

Neste guia você vai…

  1. Entender o que a integração de parceiros faz na N1
  2. Localizar o card API Keys de Parceiros em Configurações
  3. Criar e guardar API Key e Webhook Secret com segurança
  4. Gerenciar chaves e callbacks opcionais

O que esta integração faz

Em linguagem simples: um parceiro (sistema externo) pode enviar pedidos para a sua operação na N1 por API. Opcionalmente, a N1 pode avisar o parceiro quando o status do pedido mudar (por exemplo, enviado ou entregue), se você configurar um callback HTTPS.

Onde encontrar

  1. Abra o menu lateral e clique em Configurações
  2. Selecione a aba Settings
  3. Na área de cards da página, localize o card API Keys de Parceiros (há um botão Criar ao lado do título)

O texto de apoio do card diz Envie seus pedidos por API.

Passo a passo — criar a chave

  1. Clique em Criar no card API Keys de Parceiros
  2. Preencha Nome da Integração — nome interno para identificar a integração (ex.: nome da plataforma)
  3. Preencha Identificador do Parceiro — deve ser único na operação e entra no ID dos pedidos. São permitidos letras minúsculas, números, sublinhado (_) e hífen (-); outros caracteres são ajustados automaticamente. Máximo 50 caracteres
  4. Clique em Criar API Key
  5. Abre o modal Credenciais da API Key com API Key e Webhook Secret. Copie e guarde em local seguro na hora — as credenciais completas só aparecem uma vez

O que fazer com a API Key e o Webhook Secret

  • Guarde em cofre de senhas ou gerenciador de segredos do time
  • Repasse ao time técnico por canal seguro
  • Não publique em tickets abertos, grupos ou repositórios

O Webhook Secret é usado nas assinaturas criptográficas da integração (envio e recebimento de webhooks). Quem implementa a API precisa dele para assinar e validar requisições.

Gestão na lista

Para cada chave você vê nome, identificador, status (Ativa/Inativa), último uso e informações de callback quando existirem. Ações principais:

  • Interruptor: ativa ou desativa a chave sem excluir
  • Ícone de webhook: abre Callback de Status (URL HTTPS, ativar, tentativas, teste)
  • Regenerar Secret: gera um novo secret — integrações que ainda usam o antigo param de autenticar até atualizarem
  • Remover: exclui a chave permanentemente

Callbacks (opcional)

Para a N1 notificar o sistema do parceiro quando o status do pedido mudar:

  1. A URL deve ser HTTPS (a interface exige URL começando com https://)
  2. Clique no ícone de webhook na linha da chave para abrir Callback de Status
  3. Informe a URL, marque se o callback está ativo e ajuste tentativas em caso de falha
  4. Use Testar Callback para validar o endpoint antes de depender dele em produção
  5. Circuit breaker: se houver muitas falhas seguidas, o envio pode ser pausado automaticamente. O painel mostra Circuit breaker ativado e o botão Reativar depois que o endpoint for corrigido

Próximo passo

Guia técnico (endpoints, HMAC inbound/outbound, erros): API de parceiros — guia técnico.

A documentação JSON do formato de callbacks (outbound) está em: https://SEU-DOMINIO-N1.com/api/webhooks/partner/docs — use o mesmo host da sua instância N1 (onde você acessa o painel).