Documentação para desenvolvedores

API pública da S82 — leads no seu CRM

Uma API REST para exportar os dados de formulário (leads) para o seu CRM, atualizar o estágio de cada lead e atender pedidos de anonimização (LGPD). Contrato OpenAPI 1.0.0, respostas em JSON snake_case, autenticação por token Bearer.

Abrir Swagger UI interativa Baixar openapi.json Como autenticar ver a spec crua

Produçãohttps://s82.com.br/api/v1Desenvolvimento localhttp://localhost:3082/api/v1

1. Obtenha um token

A API nunca é aberta: leads são dado pessoal. Gere um token no painel administrativo, em Integrações → Tokens de API. Escolha os escopos mínimos que a integração precisa e guarde o token — ele aparece uma única vez.

Abrir Integrações no painel

Tokens são revogáveis a qualquer momento e todo acesso é registrado. Trate o token como uma senha: nunca o exponha em repositórios, front-ends ou logs.

2. Autentique-se

Envie o token no header Authorization: Bearer <token> em toda requisição. Exporte-o numa variável de ambiente para não deixá-lo no histórico do shell:

export S82_TOKEN="s82_live_…"

curl "https://s82.com.br/api/v1/leads?limit=50" \
  -H "Authorization: Bearer $S82_TOKEN"

401 — token ausente, inválido, revogado ou expirado (não distingue os casos).
403 — token válido, mas sem o escopo exigido pela operação.
Erros seguem o formato { "error": { "code", "message" } }.

Escopos

Cada token carrega um ou mais escopos. Uma operação só responde se o token tiver o escopo dela.

Escopo	Permite
`leads:read`	Ler leads — listar e obter por id.
`leads:write`	Atualizar o status de um lead.
`leads:anonymize`	Anonimizar um lead (direito do titular — LGPD).
`catalog:read`	Ler o catálogo público — serviços e posts publicados.
`events:read`	Ler o feed de eventos do site (lead.created, lead.updated, etc.).

Endpoints

Gerados a partir da spec em /api/v1/openapi.json — esta lista nunca desincroniza do contrato.

GET/api/v1/leadsleads:read

Listar leads

Lista leads em ordem decrescente de criação, paginados por cursor. Combine `updated_since` + `next_cursor` para exportação incremental contínua para o CRM.

Parâmetros

Nome	Em	Tipo	Descrição
`status`	query	`new \| contacted \| scheduled \| archived`	Filtra pelo estágio do lead no funil.
`since`	query	`string (date-time)`	Retorna leads criados a partir deste instante (created_at ≥ since). ISO 8601.
`updated_since`	query	`string (date-time)`	Retorna leads alterados a partir deste instante (updated_at ≥ updated_since). Use para sincronização incremental com o CRM. ISO 8601.
`limit`	query	`integer`	Tamanho da página.
`cursor`	query	`string`	Cursor opaco devolvido em `next_cursor` para paginar.

Requisição

curl "https://s82.com.br/api/v1/leads" \
  -H "Authorization: Bearer $S82_TOKEN"

Resposta 200

{
  "data": [
    {
      "id": "b3f1c2a4-6d7e-4a1b-9c2d-0e5f6a7b8c9d",
      "name": "Ana Ribeiro",
      "phone": "+55 41 99876-5432",
      "email": "ana.ribeiro@empresa.com.br",
      "company": "Delta Serviços",
      "role": "Head de Operações",
      "service": "ia-aplicada-ao-negocio",
      "service_name": "IA Aplicada ao Negócio",
      "message": "Queremos priorizar casos de uso de IA na operação.",
      "source_page": "/servicos/ia-aplicada-ao-negocio",
      "status": "new",
      "consent": {
        "choice": "granted",
        "policy_version": "1.0",
        "at": "2026-07-14T13:20:05.000Z"
      },
      "created_at": "2026-07-14T13:20:05.000Z",
      "updated_at": "2026-07-14T13:20:05.000Z",
      "anonymized": false
    }
  ],
  "next_cursor": "eyJpZCI6ImIzZjFjMmE0In0",
  "has_more": true
}

GET/api/v1/leads/{id}leads:read

Obter um lead

Retorna um único lead pelo seu UUID.

Parâmetros

Nome	Em	Tipo	Descrição
`id`*	path	`string (uuid)`	UUID do lead.

Requisição

curl "https://s82.com.br/api/v1/leads/b3f1c2a4-6d7e-4a1b-9c2d-0e5f6a7b8c9d" \
  -H "Authorization: Bearer $S82_TOKEN"

Resposta 200

{
  "data": {
    "id": "b3f1c2a4-6d7e-4a1b-9c2d-0e5f6a7b8c9d",
    "name": "Ana Ribeiro",
    "phone": "+55 41 99876-5432",
    "email": "ana.ribeiro@empresa.com.br",
    "company": "Delta Serviços",
    "role": "Head de Operações",
    "service": "ia-aplicada-ao-negocio",
    "service_name": "IA Aplicada ao Negócio",
    "message": "Queremos priorizar casos de uso de IA na operação.",
    "source_page": "/servicos/ia-aplicada-ao-negocio",
    "status": "new",
    "consent": {
      "choice": "granted",
      "policy_version": "1.0",
      "at": "2026-07-14T13:20:05.000Z"
    },
    "created_at": "2026-07-14T13:20:05.000Z",
    "updated_at": "2026-07-14T13:20:05.000Z",
    "anonymized": false
  }
}

PATCH/api/v1/leads/{id}leads:write

Atualizar o status de um lead

Move o lead no funil. Único campo mutável pela API é o `status`.

Parâmetros

Nome	Em	Tipo	Descrição
`id`*	path	`string (uuid)`	UUID do lead.

Requisição

curl -X PATCH "https://s82.com.br/api/v1/leads/b3f1c2a4-6d7e-4a1b-9c2d-0e5f6a7b8c9d" \
  -H "Authorization: Bearer $S82_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status":"contacted"}'

Corpo (JSON)

{
  "status": "contacted"
}

Resposta 200

{
  "data": {
    "id": "3f1c2a4e-9b8d-4c7a-8e2f-1a2b3c4d5e6f",
    "status": "contacted",
    "updated_at": "2026-07-15T09:00:00.000Z"
  }
}

POST/api/v1/leads/{id}/anonymizeleads:anonymize

Anonimizar um lead (LGPD)

Anonimização soft (LGPD art. 5º, XI): limpa nome, telefone, e-mail, empresa, cargo, mensagem e IP; preserva service/source_page/status para os relatórios de funil. Idempotente. Retorna o lead já anonimizado (`anonymized` = true).

Parâmetros

Nome	Em	Tipo	Descrição
`id`*	path	`string (uuid)`	UUID do lead.

Requisição

curl -X POST "https://s82.com.br/api/v1/leads/b3f1c2a4-6d7e-4a1b-9c2d-0e5f6a7b8c9d/anonymize" \
  -H "Authorization: Bearer $S82_TOKEN"

Resposta 200

{
  "data": {
    "id": "3f1c2a4e-9b8d-4c7a-8e2f-1a2b3c4d5e6f",
    "anonymized": true
  }
}

GET/api/v1/servicescatalog:read

Listar serviços

Catálogo público de serviços da S82, agrupável pelas 7 frentes oficiais da marca (`cluster`).

Requisição

curl "https://s82.com.br/api/v1/services" \
  -H "Authorization: Bearer $S82_TOKEN"

Resposta 200

{
  "data": [
    {
      "slug": "ia-aplicada-ao-negocio",
      "name": "IA Aplicada ao Negócio",
      "cluster": "IA & Dados",
      "summary": "Mapeamento de oportunidades de IA, priorização por impacto no negócio e adoção responsável — com governança, ética e capacitação das equipes."
    }
  ]
}

GET/api/v1/postscatalog:read

Listar posts publicados

Posts do blog em estado publicado. Rascunhos e agendados não são expostos.

Requisição

curl "https://s82.com.br/api/v1/posts" \
  -H "Authorization: Bearer $S82_TOKEN"

Resposta 200

{
  "data": [
    {
      "slug": "governanca-de-ia-nas-empresas",
      "title": "Governança de IA nas empresas: por onde começar",
      "excerpt": "Um roteiro prático para adotar IA com controle, ética e indicadores.",
      "cluster": "IA & Dados",
      "url": "https://s82.com.br/blog/governanca-de-ia-nas-empresas",
      "published_at": "2026-06-10T12:00:00.000Z",
      "updated_at": "2026-06-10T12:00:00.000Z"
    }
  ]
}

GET/api/v1/eventsevents:read

Listar eventos do site (feed pull)

Feed de eventos do site para consumir por polling — o MESMO objeto que os webhooks entregam por push. Tipos: `lead.created`, `lead.updated`, `lead.anonymized`, `post.published`. Paginação por cursor keyset em (created_at, id).

Parâmetros

Nome	Em	Tipo	Descrição
`type`	query	`lead.created \| lead.updated \| lead.anonymized \| post.published`	Filtra por tipo de evento.
`since`	query	`string (date-time)`	Retorna eventos criados a partir deste instante (created_at ≥ since). ISO 8601.
`limit`	query	`integer`	Tamanho da página.
`cursor`	query	`string`	Cursor opaco devolvido em `next_cursor` para paginar.

Requisição

curl "https://s82.com.br/api/v1/events" \
  -H "Authorization: Bearer $S82_TOKEN"

Fluxo de exportação para o CRM

Para uma sincronização incremental e contínua: puxe apenas o que mudou desde a última sync, pagine por cursor até esgotar, e devolva mudanças de estágio via PATCH.

1Guarde o instante da última sincronização (lastSyncedAt, ISO 8601).
2Chame GET /leads?updated_since=<lastSyncedAt>.
3Grave cada lead no CRM e, enquanto has_more for true, repita com ?cursor=<next_cursor>.
4Ao mover um lead no seu funil, reflita de volta com PATCH /leads/{id}.

let cursor = null
do {
  const url = new URL('https://s82.com.br/api/v1/leads')
  url.searchParams.set('updated_since', lastSyncedAt) // ISO 8601 da última sync
  if (cursor) url.searchParams.set('cursor', cursor)

  const res = await fetch(url, {
    headers: { Authorization: `Bearer ${S82_TOKEN}` },
  })
  const { data, next_cursor, has_more } = await res.json()

  for (const lead of data) upsertIntoCrm(lead)   // grava/atualiza no CRM
  cursor = next_cursor
} while (has_more)

// devolva mudanças de estágio para a S82:
await fetch(`https://s82.com.br/api/v1/leads/${leadId}`, {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${S82_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ status: 'contacted' }),
})

Importar no Postman, Insomnia ou no seu CRM

A spec OpenAPI é a maneira mais rápida de subir todos os endpoints de uma vez:

Postman / Insomnia

Import → Link e cole a URL abaixo. As requisições e schemas são criados automaticamente. Depois, defina a variável S82_TOKEN.

https://s82.com.br/api/v1/openapi.json

CRM com conector OpenAPI

Aponte o conector para o mesmo arquivo openapi.json e configure o auth type como Bearer Token com o token do painel. O escopo mínimo para importar leads é leads:read.

Dúvidas de integração? Fale com a S82 Tecnologia em contato@s82.com.br.