Guia de estudo para a equipe entender APIs, ler documentação e montar automações no n8n. Conceitos explicados do zero, com exercícios baseados na API da SenseData.
Você vai ver estas palavras o tempo todo. Aqui está cada uma em português claro. Não precisa decorar — volte aqui sempre que esbarrar num termo.
Antes de tocar em qualquer código, é preciso entender o problema que as APIs resolvem: fazer sistemas que foram construídos por empresas diferentes, em linguagens diferentes, conversarem entre si de forma confiável.
Este vídeo explica o conceito de API com a analogia do Restaurante da Selva: você entende como os sistemas se comunicam sem que o cliente precise saber o que acontece na "cozinha" (o servidor). Ele cobre, em poucos minutos, quase tudo que os primeiros módulos aprofundam — vale assistir antes de seguir.
Um sistema é qualquer software que guarda e processa informação. No dia a dia você convive com vários, e quase nunca eles "nascem" sabendo conversar uns com os outros:
Gestão interna de uma empresa: notas fiscais, estoque, financeiro.
Relacionamento com clientes: leads, oportunidades, funil de vendas.
Captura, processa e transmite documentos fiscais (NF-e, SPED) entre o contribuinte e os sistemas da Receita.
Canais de entrada e saída de dados que precisam ser conectados ao resto.
Como o Site avisa o CRM que chegou um lead? Como o WhatsApp manda um pedido para o ERP? Como o ERP envia um lançamento para o sistema financeiro? Sem um "idioma comum" e uma "porta de entrada", cada integração viraria uma gambiarra frágil. A resposta para isso é a API.
A API é o garçom do restaurante. Você (o cliente) não entra na cozinha nem mexe nas panelas. Você faz um pedido pelo cardápio (a documentação), o garçom leva à cozinha (o servidor), a cozinha processa, e o garçom traz a resposta — seu prato ou um "acabou o ingrediente". A API esconde a complexidade e expõe só o que você pode pedir.
| Conceito | O que é | No exemplo do iFood |
|---|---|---|
| Cliente | Quem faz o pedido | O app no seu celular |
| Servidor | Quem processa e guarda os dados | Os servidores do iFood |
| Requisição | A mensagem de pedido enviada | "Quero ver restaurantes perto de mim" |
| Resposta | O retorno com dados ou status | A lista de restaurantes em JSON |
Toda API REST conversa por cima do HTTP — o mesmo protocolo que seu navegador usa para abrir sites. Dominar HTTP é dominar 70% das integrações.
Quando você digita um endereço, o navegador manda uma requisição para um servidor, que devolve uma resposta (o HTML da página). Uma API faz exatamente o mesmo — só que devolve dados (JSON) em vez de uma página bonita.
HTTP (HyperText Transfer Protocol) é o conjunto de regras que define como cliente e servidor trocam mensagens: qual ação está sendo pedida, qual o endereço, quais dados vão junto e o que voltou.
O verbo diz a intenção da requisição. O mesmo endereço pode se comportar de formas diferentes dependendo do verbo usado.
Na API da SenseData v2, qual verbo HTTP você usaria para cada tarefa de Customer Success?
| Tarefa real | Seu verbo |
|---|---|
| Listar os clientes da carteira | … |
| Importar novos clientes vindos do ERP | … |
| Atualizar só o CSM responsável de um cliente | … |
| Apagar uma nota de cliente lançada por engano | … |
Antes de qualquer integração, valide seu token (sua senha de acesso à API) chamando GET https://api.sensedata.io/v2/me e enviando, junto, o header (cabeçalho) Authorization: Bearer <token>. Se voltar 200 com os seus dados de usuário, a credencial está válida — e você já tem a base de toda a API.
Calma: você ainda não sabe onde digitar isso. No Módulo 5 você instala o Postman e faz essa chamada na prática, passo a passo. A documentação oficial de todos os endpoints fica em api.sensedata.io/v2/redoc.
JSON (JavaScript Object Notation) é o formato em que praticamente toda API moderna troca dados. É só texto, legível por humanos e por máquinas. Se você entende JSON, você entende o que entra e sai de qualquer integração.
{
"nome": "João",
"idade": 30,
"cidade": "São Paulo"
}"nome": "João""idade": 30"ativo": true"telefones": [
"11999999999",
"11888888888"
]"endereco": {
"cidade": "São Paulo",
"uf": "SP"
}Vírgula sobrando após o último item; aspas simples em vez de duplas (JSON exige aspas duplas); chave sem aspas. Um validador como jsonlint.com aponta o erro na hora.
O endpoint (o endereço dentro da API) POST /v2/customers exige os campos: id_legacy, name_contract, name, dt_register, status, cs e csm. Monte o JSON de um cliente, lembrando que status, cs e csm são objetos (uma referência a outro cadastro — chamamos de FK, "chave estrangeira").
A SenseData aceita arrays em POST/PATCH para inserção em lote. Monte um corpo que crie dois clientes de uma vez — é assim que se sincroniza uma carteira inteira sem estourar rate limit.
REST é o padrão arquitetural mais usado para construir APIs. A ideia central: organizar a API em torno de recursos (substantivos) e usar os verbos HTTP para agir sobre eles.
https://api.empresa.com/clientes
└──────────┬─────────┘ └───┬───┘
base URL recursoRecursos comuns: /clientes, /produtos, /pedidos. Repare que são sempre substantivos no plural — nunca verbos. A ação quem define é o método HTTP.
O endereço diz com o quê você está mexendo (o recurso). O verbo diz o que você quer fazer. /clientes é o mesmo endereço para listar (GET) e para criar (POST) — muda só o verbo.
O que cada chamada faz na API v2?
Agora você vai disparar requisições de verdade. As ferramentas mais usadas são Postman, Insomnia e Bruno — todas deixam você montar a requisição peça por peça e ver a resposta.
| Peça | Para que serve | Exemplo |
|---|---|---|
| Headers | Metadados: formato, autenticação | Content-Type: application/json |
| Path Param | Identifica um item na própria URL | /users/2 |
| Query Param | Filtra / pagina, após o ? | /users?page=2 |
| Body | Os dados enviados (em POST/PUT/PATCH) | JSON do novo registro |
// GET https://reqres.in/api/users/2
{
"data": {
"id": 2,
"email": "janet.weaver@reqres.in",
"first_name": "Janet"
}
}O Postman é um programa gratuito onde você monta e dispara requisições clicando — não precisa programar nada. É a forma mais fácil de fazer sua primeira chamada de verdade. Vamos do download até a primeira resposta.
Abra o navegador e vá em postman.com/downloads. O site detecta seu sistema automaticamente.
Windows Clique em Windows 64-bit. Vai baixar um arquivo Postman-win64-Setup.exe.
Mac Clique em Mac Apple Chip (para os MacBooks M1/M2/M3/M4) ou Mac Intel Chip nos modelos mais antigos.
Windows Dê dois cliques no arquivo baixado. A instalação é automática — em poucos segundos o Postman abre sozinho.
Mac Abra o arquivo .zip/.dmg baixado e arraste o ícone do Postman para a pasta Aplicativos. Depois abra pelo Launchpad.
O Postman pede para criar conta. Você pode criar uma grátis (útil para salvar seu trabalho na nuvem) ou clicar em "Continue without an account" / "Skip", no rodapé, para usar offline. Para o treinamento, qualquer opção serve.
Clique no botão New (ou no + ao lado das abas). Vai abrir uma aba em branco com uma barra no topo: um seletor de método (começa em GET) e um campo de URL ("Enter URL").
Deixe o método em GET. No campo de URL, cole o nosso primeiro endereço de teste:
https://api.sensedata.io/v2/meEsse endereço apenas devolve "quem é você" — é o teste mais seguro para começar, não altera nada.
Logo abaixo da barra de URL há uma fileira de abas: Params · Authorization · Headers · Body. Clique em Authorization.
No campo "Type", escolha Bearer Token. Vai aparecer uma caixa "Token" à direita. Cole ali o seu token (aquele código que a SenseData fornece). Pronto — é exatamente esse o "onde colocar o token".
Aperte o botão azul/amarelo Send. Na metade de baixo da tela aparece a resposta: um JSON com seus dados e, no canto, o status. Se vier 200 OK em verde, deu tudo certo — seu token funciona!
401 → token errado, vazio, ou faltou escolher "Bearer Token". 404 → URL digitada errada. 429 → você fez chamadas demais, espere um pouco. (A tabela completa está no Módulo 10.)
Para não colar o token toda hora, clique no ícone de olho no canto superior direito → Add em "Environment". Crie uma variável chamada token e cole o valor lá uma única vez. Depois, na aba Authorization, escreva {{token}} no lugar do token. Assim você troca a credencial em um só lugar.
O Insomnia e o Bruno são alternativas gratuitas ao Postman e funcionam quase igual: método, URL, aba de Auth para o Bearer Token e botão de enviar. Se você aprendeu no Postman, usa qualquer um deles sem dificuldade. O Bruno é leve e guarda tudo em arquivos no seu computador.
Agora no Postman: monte a URL que lista os clientes cancelados em 2025, trazendo 100 por página. Cole no campo de URL, mantenha o método em GET e o Bearer Token na aba Authorization, e clique em Send. Dica: a SenseData filtra por data com os sufixos :start e :end e pagina com limit e page.
Você quer (a) o cliente de id interno 8821 e (b) todos os contatos ativos desse mesmo cliente. Escreva as duas chamadas.
POST /v2/contacts exige: customer, is_main_sponsor, is_active e name. Crie o contato principal de um cliente, referenciando-o pela chave do ERP.
[
{
"customer": { "id_legacy": "ERP-4471" },
"name": "Leônidas Ferreira",
"email": "leonidas@contabilidademodelo.com.br",
"occupation": "Sócio-diretor",
"is_main_sponsor": true,
"is_active": true
}
]APIs sérias não são abertas: elas precisam saber quem está chamando e se essa pessoa pode. Isso evita abuso, permite cobrança e protege dados. A credencial quase sempre viaja num header.
Uma chave fixa enviada num header. Simples, comum em integrações servidor-a-servidor.
x-api-key: abc123Um token (muitas vezes temporário) enviado no header Authorization.
Authorization:
Bearer eyJhbGci…Fluxo onde o app troca credenciais por um token de acesso, sem expor a senha do usuário.
Nunca coloque chaves ou tokens dentro da URL nem em código versionado no Git. Use variáveis de ambiente / credenciais do n8n. Trate todo token como se fosse uma senha.
Você chamou GET https://api.sensedata.io/v2/customers e recebeu 401. O que aconteceu e como resolver?
Até aqui você chamava a API. Webhook é o inverso: a API chama você quando algo acontece. É a base de quase toda automação em tempo real.
Seu sistema fica perguntando de minuto em minuto: "tem novidade? e agora? e agora?". Desperdiça recursos e atrasa.
Você registra uma URL. Quando o evento ocorre, o outro sistema dispara um POST para você na hora. Zero desperdício.
Crie um nó Webhook (no n8n) e faça-o receber o payload abaixo. Depois, visualize os dados recebidos.
{
"nome": "Maria",
"email": "maria@email.com"
}Sua ferramenta de pesquisa (ex.: formulário de NPS) dispara um webhook a cada resposta. Receba o payload no n8n e registre a resposta na SenseData via POST /v2/nps (obrigatórios: id_legacy, customer, ref_date, survey_date, medium, respondent, score).
// payload recebido no webhook
{ "cnpj": "12345678000190", "quem": "leonidas@cliente.com.br", "nota": 9 }O n8n é uma ferramenta de automação visual: em vez de escrever todo o código de integração, você arrasta nodes (nós) e os conecta formando um fluxo. Cada node faz uma coisa; os dados fluem de um para o outro.
| Conceito | O que é |
|---|---|
| Trigger | O node que inicia o fluxo (Webhook, agendamento, novo e-mail…) |
| Node | Uma etapa: chamar API, transformar dado, gravar em planilha… |
| Conexão | A "linha" por onde os dados passam de um node ao próximo |
| Execução | Uma rodada completa do fluxo, com dados reais percorrendo os nodes |
O n8n roda em nuvem (n8n.cloud) ou self-hosted num VPS via Docker. Para integrações com dados sensíveis, o self-hosted dá controle total — coerente com cenários onde já se avalia VPS próprio para orquestração.
Crie um fluxo Webhook → Set → Google Sheets que receba nome e e-mail e grave uma linha na planilha. Ative e teste com a URL de produção.
O que separa um fluxo bonito de um fluxo que funciona é a manipulação de dados. Aqui você aprende a pescar exatamente o campo certo de dentro de um JSON e a transformar listas.
No n8n, você acessa dados de nodes anteriores com expressions, escritas entre {{ }}. O caminho até o dado é o JSON Path.
// dado de entrada
{ "cliente": { "nome": "João" } }// expression para extrair "João"
{{ $json.cliente.nome }} // → JoãoCria, renomeia e remodela campos para o formato que o próximo sistema espera.
Junta dados de dois ramos — ex.: combinar o lead com o resultado de uma API de enriquecimento.
Quebra um array em itens individuais para processar um a um (Split Out / Loop Over Items).
A resposta de GET /v2/customers/8821 chega assim. Escreva a expression que devolve o e-mail do CSM.
{
"id": 8821,
"name": "Contabilidade Modelo",
"csm": { "name": "Bruno", "email": "bruno.csm@empresa.com.br" }
}Você buscou os clientes com NPS detrator e recebeu um array. Crie uma atividade (POST /v2/tasks) para o CSM acompanhar cada cliente da lista.
Integração que não trata erro é integração que falha em silêncio. Saber ler o status HTTP da resposta é a habilidade de diagnóstico número um.
| Código | Família | Significado |
|---|---|---|
| 200 | Sucesso | OK — deu certo |
| 201 | Sucesso | Created — recurso criado (típico de POST) |
| 400 | Erro do cliente | Bad Request — você mandou algo malformado |
| 401 | Erro do cliente | Unauthorized — falta autenticação válida |
| 403 | Erro do cliente | Forbidden — autenticado, mas sem permissão |
| 404 | Erro do cliente | Not Found — recurso não existe |
| 422 | Erro do cliente | Unprocessable Entity — falha de validação (campo obrigatório/FK) |
| 429 | Erro do cliente | Too Many Requests — você estourou o rate limit |
| 500 | Erro do servidor | Internal Server Error — o problema é do outro lado |
2xx = "deu certo". 4xx = "o erro foi seu" (cliente). 5xx = "o erro foi deles" (servidor). Só isso já direciona 90% do diagnóstico: se é 4xx, revise sua requisição; se é 5xx, o problema está no servidor e cabe retry.
Tentar de novo automaticamente em falhas temporárias (5xx, 429), com espera crescente entre tentativas (backoff).
Definir um tempo máximo de espera para não travar o fluxo indefinidamente quando a API não responde.
Registrar o que entrou, o que voltou e o erro. Sem log, você fica cego quando algo quebra em produção.
Cada node tem Settings → Retry On Fail e Continue On Fail. Use um Error Trigger num fluxo separado para capturar qualquer falha e notificar a equipe automaticamente.
Caso 1: GET /v2/customers/9999 retornou 404.
Caso 2: POST /v2/customers retornou 422 em um dos itens do array.
Diagnostique cada um.
Primeiro projeto ponta a ponta. Um formulário capta um lead; o n8n recebe, organiza, registra no CRM e dispara avisos por e-mail e WhatsApp. É o fluxo que mais gera valor comercial imediato.
Fluxo n8n ativo que, ao receber um lead, cria o contato no CRM e notifica a equipe. Inclua ao menos um node de validação (IF) descartando leads sem e-mail.
Aqui o foco é confiabilidade. Dados saem do Sistema A, passam pelo n8n e entram no Sistema B. Dinheiro não admite falha silenciosa: autenticação, logs e tratamento de erro são obrigatórios.
Em integração financeira, reenviar o mesmo lançamento duas vezes é desastre. Garanta idempotência: use um identificador único por transação para que o Sistema B reconheça e ignore duplicatas (ver Módulo 13). Na SenseData, esse papel é do id_legacy — a chave do seu sistema de origem, usada para deduplicação.
Concretizando o projeto com a SenseData: extraia faturas do ERP e grave em POST /v2/billing (obrigatórios: id_legacy, customer, ref_doc, ref_invoice, due_date, invoice_date, amount, status). Depois, quando o cliente pagar, atualize via PATCH /v2/billing.
Os conceitos que aparecem quando você sai de exemplos de tutorial e encara APIs reais de produção, com milhares de registros e limites rígidos.
APIs não devolvem 50 mil registros de uma vez. Elas paginam: ?page=2&per_page=100 ou via cursor. Seu fluxo precisa percorrer todas as páginas até o fim.
Limite de chamadas por janela de tempo. Estourou? Vem o 429. Respeite o header Retry-After e use backoff.
APIs evoluem sem quebrar quem já usa: /v1/clientes, /v2/clientes. Saiba qual versão você consome.
Guardar respostas que mudam pouco evita chamadas repetidas e melhora performance. Headers como ETag e Cache-Control governam isso.
Repetir a mesma requisição não deve criar efeitos duplicados. Chave de idempotência protege POSTs sensíveis (pagamentos).
A resposta traz links para as próximas ações possíveis, tornando a API auto-descritiva. Mais raro, mas bom conhecer.
A maioria das APIs sérias publica um arquivo OpenAPI (antes "Swagger"): a especificação legível por máquina de todos os endpoints, parâmetros e respostas. É o "mapa oficial" — saber lê-lo encurta qualquer integração.
A referência completa da API v2 está publicada em formato ReDoc, com todos os endpoints, parâmetros, campos obrigatórios e exemplos de resposta:
https://api.sensedata.io/v2/redoc
Use essa página como seu "mapa oficial": ao precisar de um endpoint novo, procure-o ali e extraia os cinco itens acima (endpoint, método, headers, body, respostas) antes de montar a chamada no Postman ou no n8n.
Você precisa extrair toda a base de clientes (são ~2.300). A SenseData devolve no máximo 100 por página. Descreva o laço que garante trazer todos sem perder nenhum.
Durante a importação em lote, a SenseData começou a responder 429. O que está acontecendo e qual a estratégia correta?
Você quer o health score de um cliente nos últimos 6 meses. Consultando a doc oficial (api.sensedata.io/v2/redoc): qual a sequência de chamadas e a URL final?
O módulo que transforma um operador de n8n em um arquiteto: saber qual mecanismo escolher para cada problema, e por quê.
| Mecanismo | Use quando |
|---|---|
| API (request) | Você precisa de uma resposta na hora. Comunicação síncrona. |
| Webhook | Reagir a eventos do outro sistema em tempo real, sem ficar perguntando. |
| Fila (queue) | Volume alto ou picos: desacopla produtor e consumidor, processa no ritmo possível. |
| Banco de dados | Persistir estado, histórico, logs e dados de referência consultáveis. |
Pede e espera a resposta antes de continuar. Simples, mas trava se o outro lado demora.
Dispara e segue a vida; a resposta chega depois (callback/webhook/fila). Resiliente.
O sistema reage a eventos publicados. Componentes desacoplados, escala melhor.
Esta é uma das primeiras decisões de qualquer integração: usar uma conexão pronta que a ferramenta já oferece, ou construir você mesmo a chamada à API. As duas levam ao mesmo lugar — a diferença é quanto trabalho, controle e manutenção cada uma exige.
A ferramenta (n8n, Zapier, Make…) já traz um nó/conector daquele serviço. Você só faz login, escolhe a ação numa lista e preenche os campos. A autenticação, o formato do JSON e o tratamento de erro já vêm prontos.
Ex.: no n8n, o nó "Gmail" ou "Google Sheets" — clicou, conectou a conta, pronto.
Não existe conector pronto (ou ele não cobre o que você precisa), então você usa um nó genérico de HTTP Request e monta a chamada na mão: método, URL, header com o token, body em JSON. É exatamente o que você aprendeu nos módulos anteriores.
Ex.: a SenseData não tem um nó dedicado no n8n — então você integra via HTTP Request, montando GET /v2/customers com o Bearer token.
| Critério | Nativa (conector) | API custom (HTTP) |
|---|---|---|
| Rapidez para montar | Alta — poucos cliques | Menor — você configura tudo |
| Conhecimento exigido | Baixo | Médio — REST, JSON, auth, erros |
| Flexibilidade | Limitada ao que o conector expõe | Total — qualquer endpoint da API |
| Manutenção | O fornecedor atualiza o conector | Sua — se a API mudar, você ajusta |
| Quando a API muda | Costuma continuar funcionando | Pode quebrar e exigir correção |
| Disponível para | Só serviços populares | Qualquer API com documentação |
Se existe um conector nativo que faz o que você precisa, use-o — é mais rápido e exige menos manutenção. Parta para a API custom (HTTP Request) quando não houver conector, quando ele não cobrir a ação específica, ou quando você precisar de um endpoint que só a API oferece. No caso da SenseData, como não há nó dedicado, o caminho é sempre o HTTP Request.
Para cada tarefa, decida o caminho mais sensato:
Escolha um processo do seu trabalho e desenhe a arquitetura completa: o que é síncrono, o que é assíncrono, onde entram webhooks, onde fica o log e onde os dados são armazenados para análise.
Um projeto realista do dia a dia de Customer Success, usando só o que você aprendeu e endpoints reais da SenseData. Objetivo: quando um cliente responde uma pesquisa de NPS com nota baixa (detrator), o CSM responsável é avisado na hora e já recebe uma tarefa de acompanhamento — sem ninguém precisar ficar olhando relatório.
A pesquisa de NPS dispara um webhook a cada resposta. Se a nota for de 0 a 6 (detrator), o fluxo busca quem é o cliente e o CSM dele, cria uma tarefa de contato e notifica o time. Notas 7+ são apenas registradas. É um fluxo curto, seguro e de valor imediato para a carteira.
Funcionando, ativo e testado com respostas de NPS de exemplo.
Os endpoints da SenseData usados: método, header de token, body e respostas.
De-para: campos do webhook de NPS → campos da tarefa na SenseData.
Retry em 429/5xx e notificação ao time em caso de falha.
Visão geral de quem dispara o quê, do webhook ao log.
Concluindo este projeto, você sai de "não sei o que é uma API" e passa a construir, sozinho, uma automação real de Customer Success — lendo a documentação da SenseData, montando requisições, tratando erros e orquestrando tudo no n8n.