Apps parceiros

O modelo em uma tela

1. A pessoa é dona do projeto. Os dados são dela. O seu app não é dono de nada, mesmo que tenha sido ele a trazê-la para o CrazyLeads.
2. O app lê por concessão dela. A concessão é um token ligado a três coisas: o seu app, a pessoa e um projeto. Ela pode revogar quando quiser, sem avisar — e a chamada seguinte falha.
3. O escopo é do projeto inteiro. Não existe autorização por fonte nem por tipo de dado: o que ela conectar depois de autorizar, o seu app também lê. Fonte nova não exige nova autorização.
4. A autorização acontece na tela do CrazyLeads. Você redireciona; ela vê o nome do seu app, o que ele vai poder fazer, escolhe ou cria o projeto e autoriza. Seu app nunca vê a senha dela.

Do zero ao primeiro dado são seis passos: registrar e homologar → mandar autorizar → trocar o código por token → ler pela /v1 → pedir atualização → tratar a revogação. Cada um está abaixo, com o pedido e a resposta reais.

1. Registrar o aplicativo

Um app parceiro é registrado pela equipe do CrazyLeads, não por formulário público. Você manda os dados abaixo e recebe um client_id. Não existe segredo de cliente: a segurança do fluxo vem do PKCE, que é obrigatório.

Homologação

O app nasce registrado, mas não homologado. A homologação é a aprovação do CrazyLeads, e ela é conferida a cada chamada, não só no momento em que a pessoa autoriza. Enquanto o app não está homologado:

• /oauth/authorize recusa qualquer escopo de parceiro com a tela Invalid scope, antes mesmo de a pessoa entrar;
• /api/oauth/token responde invalid_scope, na troca do código e na renovação;
• a /v1 responde 403 insufficient_scope.

Suspender um app desfaz a homologação: o acesso cessa na chamada seguinte, sem precisar revogar token a token. Os tokens continuam existindo e voltam a valer se a homologação voltar.

2. Mandar a pessoa autorizar (OAuth 2.1 + PKCE)

O fluxo é o authorization code do OAuth 2.1 com PKCE S256. Os endereços saem do documento de descoberta — leia-o em vez de escrevê-los na mão:

GET https://crazyleads.com.br/api/well-known/oauth-authorization-server

Hoje o único método de desafio é S256, o único tipo de resposta é code e o único método de autenticação do cliente é none. O campo scopes_supported desse documento lista apenas os escopos do MCP; os escopos de parceiro são os da tabela desta página.

Passo 1 — gere o verificador e o desafio

Um code_verifier aleatório de 43 a 128 caracteres, guardado no seu servidor, e o code_challenge = base64url do SHA-256 dele.

code_verifier=$(openssl rand -base64 48 | tr -d '=+/' | cut -c1-64)
code_challenge=$(printf '%s' "$code_verifier" \
  | openssl dgst -sha256 -binary | openssl base64 -A | tr '+/' '-_' | tr -d '=')

Passo 2 — abra a URL de autorização no navegador da pessoa

https://crazyleads.com.br/oauth/authorize
  ?response_type=code
  &client_id=SEU_CLIENT_ID
  &redirect_uri=https://meuapp.com.br/callback
  &scope=project:read data:instagram:read data:analytics:read project:refresh offline_access
  &state=UM_VALOR_ALEATORIO_SEU
  &code_challenge=$code_challenge
  &code_challenge_method=S256
  &login_hint=ana@exemplo.com.br
  &project_name=Mentoria da Ana

A pessoa entra (se ainda não estiver logada, a tela de entrada sabe que é o seu app que está esperando), vê o nome e o logotipo do app, a lista do que ele vai poder fazer — uma linha por escopo pedido, com a frase da tabela de escopos —, o endereço para onde o acesso será entregue, e escolhe o projeto entre os que ela participa, com qualquer papel — e a última opção do seletor é sempre “Criar um projeto novo”, tenha ela projetos ou não.

Na volta, chegam três parâmetros na sua URI de retorno:

https://meuapp.com.br/callback
  ?code=clc_…
  &state=UM_VALOR_ALEATORIO_SEU
  &iss=https://crazyleads.com.br

Confira state e iss antes de usar o código. Se a pessoa recusar, em vez de code vem error=access_denied — trate como resposta normal, não como falha. O código vale 10 minutos e serve uma única vez; trocá-lo duas vezes revoga tudo o que ele emitiu.

Passo 3 — troque o código por tokens

O corpo vai como formulário, não como JSON.

curl -X POST https://crazyleads.com.br/api/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d grant_type=authorization_code \
  -d code=O_CODIGO_QUE_VOLTOU \
  -d client_id=SEU_CLIENT_ID \
  -d redirect_uri=https://meuapp.com.br/callback \
  -d code_verifier=$code_verifier

{
  "access_token": "cla_…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "clr_…",
  "scope": "data:analytics:read data:instagram:read offline_access project:read project:refresh"
}

Leia o campo scope: é o que foi concedido, e ele pode ser menor que o pedido. Guarde os dois tokens no servidor; nenhum deles é para o navegador.

Passo 4 — renove antes de o acesso expirar

curl -X POST https://crazyleads.com.br/api/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d grant_type=refresh_token \
  -d refresh_token=SEU_TOKEN_DE_RENOVACAO \
  -d client_id=SEU_CLIENT_ID

A resposta tem a mesma forma da troca: um token de acesso novo e um token de renovação novo. O anterior deixa de valer no mesmo instante, e todos os tokens de acesso emitidos por ele são revogados. Grave o novo antes de usá-lo.

Passo 5 — a primeira chamada

curl https://crazyleads.com.br/api/v1/projects \
  -H "Authorization: Bearer SEU_TOKEN_DE_ACESSO"

{
  "data": [
    {
      "id": "00000000-0000-4000-8000-000000000001",
      "name": "Mentoria da Ana",
      "status": "ready",
      "created_by_me": false
    }
  ],
  "next_cursor": null
}

O token vale para um projeto — o que a pessoa escolheu na tela. Esta lista tem zero ou um item, e o id é o que você usa nas rotas que levam o projeto no caminho.

Pedir que a pessoa conecte uma fonte

Quando o seu app precisa de uma fonte que o projeto ainda não tem, peça o escopo de conexão dela junto com os demais. Depois de autorizar, a pessoa vai direto para o fluxo de conexão daquela fonte, numa tela do CrazyLeads sem navegação, e volta ao seu app no fim, com o code, pela sua URI de retorno. Cada fonte segue o próprio caminho:

O escopo de conexão tem de estar no registro do seu app, como qualquer outro, e não libera nenhuma rota da /v1: ele só diz o que a pessoa vai conectar agora. Para ler o que chegar da fonte, peça também o escopo de leitura, como project:read ou data:instagram:read. Seu app nunca vê a credencial que a pessoa digita.

Pedido mais de um escopo de conexão, as fontes vêm uma depois da outra, na ordem da tabela, e a pessoa pode pular qualquer uma. A que já está conectada no projeto é pulada sozinha; se todas já estiverem, a autorização segue direto para o seu app, como sem escopo de conexão.

A autorização fica guardada enquanto a pessoa conecta: 30 minutos, renovados sozinhos enquanto ela está na tela, até 2 horas depois de autorizar. Passado isso, a tela avisa e ela precisa autorizar de novo; o que já foi conectado continua conectado. Para pedir outra fonte mais tarde, mande a pessoa de novo pelo /oauth/authorize com o escopo de conexão dela.

Por compatibilidade, data:instagram:read num projeto sem Instagram conectado também leva a pessoa à conexão do Instagram. Prefira pedir source:instagram:connect de forma explícita.

3. Os escopos, e o que a pessoa lê ao lado de cada um

A tela de consentimento mostra uma linha por escopo pedido, com a frase abaixo — nem mais, nem menos. As escritas que existem são estreitas — data:analytics:write só edita o que o seu app criou, e data:instagram:write só modera comentários da conta conectada — e nenhum escopo é desmarcável: ou a pessoa autoriza o que o seu app precisa para existir, ou cancela.

Escopo que o seu registro não inclui é descartado em silêncio na autorização; escopo que a tela ainda não sabe nomear aparece pelo nome técnico, nunca some. Em qualquer caso, o que vale é o scope da resposta do token.

4. Referência da API /v1

Base: https://crazyleads.com.br/api/v1. Toda chamada leva Authorization: Bearer SEU_TOKEN_DE_ACESSO. O projeto vem do token, nunca de um parâmetro seu; nas rotas que levam {prj} no caminho, ele tem de ser o mesmo projeto da concessão — outro qualquer é 404.

Paginação

As listas paginam por cursor: limit de 1 a 100 (padrão 50) e next_cursor na resposta — repita passando ?cursor= até ele vir null. O cursor é opaco e assinado: não interprete o conteúdo nem monte um na mão. limit fora da faixa é 400, e não é aparado em silêncio — pedir 1.000 e receber 100 faria você concluir que a coleção acabou.

Datas

Todo horário sai em ISO 8601 em UTC. O deslocamento aparece como Z, +00:00 ou +0000 conforme a origem do campo (carimbos do CrazyLeads, do banco e da Meta, respectivamente). Use um parser que leia o deslocamento; não compare sufixo nem converta para o fuso de Brasília por conta própria. As demais convenções — erros, versão, idempotência — estão em Convenções da API.

As rotas

GET /api/v1/projects

Sem parâmetros. status é ready ou frozen — um projeto congelado continua listado, mas o dado dele não é atualizado. created_by_me diz se foi o seu app que criou o projeto; hoje é sempre false, porque a criação acontece na tela de autorização. O exemplo está no passo 5.

GET /api/v1/sources

Parâmetros: limit, cursor. Ordem por id.

{
  "data": [
    {
      "id": "00000000-0000-4000-8000-000000000002",
      "type": "META",
      "name": "Instagram da mentoria",
      "slug": "instagram_da_mentoria",
      "connected": true,
      "last_synced_at": "2026-09-16T11:04:12+00:00",
      "last_error": null
    }
  ],
  "next_cursor": null
}

type é o tipo da fonte no CrazyLeads (META, HOTMART, PIXEL, WEBHOOK, DATABASE, entre outros). connected falso com last_error preenchido é uma fonte que precisa da atenção da pessoa — o seu app não consegue reconectá-la.

POST /api/v1/sources/{id}/sync

Sem corpo. Pede ao CrazyLeads que sincronize a fonte agora, pelo mesmo caminho que o botão do produto usa. A resposta é 202: o pedido foi aceito e acontece em segundo plano; acompanhe pelo last_synced_at de GET /api/v1/sources.

{
  "accepted": true,
  "task": "5b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e",
  "last_synced_at": "2026-09-16T11:04:12+00:00"
}

Sujeito aos tetos de sincronização — veja o 429.

GET /api/v1/tables

O catálogo do projeto: cada tabela com as colunas, os tipos e a fonte que a alimenta. É por aqui que o seu app descobre o que existe antes de escrever qualquer consulta.

{
  "data": [
    {
      "name": "meta_jornal_mangueiral_instagram_media",
      "schema": "project__0f1e2d3c_4b5a_6978_8a9b_0c1d2e3f4a5b",
      "qualified_name": "project__0f1e2d3c_4b5a_6978_8a9b_0c1d2e3f4a5b.meta_jornal_mangueiral_instagram_media",
      "entity_type": "stream",
      "source": { "id": "8f2c…", "name": "Meta Organic", "type": "META_PAGES_INSTAGRAM", "slug": "jornal_mangueiral" },
      "row_count": 3412,
      "columns": [
        { "name": "object_id", "type": "text", "nullable": false },
        { "name": "timestamp", "type": "text", "nullable": true }
      ]
    }
  ]
}

row_count é ESTIMATIVA, lida do catálogo do Postgres. Contar linha por linha em toda tabela seria varredura no banco de escrita, e o número serve para dimensionar, não para conferir.

schema é o schema do projeto da concessão, e qualified_name é o nome que o SQL precisa usar: toda tabela citada numa consulta vai com o schema na frente. Use o qualified_name como veio, sem montar o nome à mão.

POST /api/v1/sql/query

Roda um SELECT no projeto e devolve as linhas. O SQL passa por uma guarda que só aceita leitura, exige que toda tabela venha com o schema do projeto (o qualified_name do catálogo) e trabalha com uma lista fechada de funções. Recusa é 400 com um reason de máquina, e é PERMANENTE: o mesmo texto será recusado sempre, então não vale retentar.

{
  "sql": "WITH recentes AS (SELECT media_type FROM project__0f1e…4a5b.meta_jornal_mangueiral_instagram_media WHERE data->>'timestamp' >= to_char(now() - interval '30 days', 'YYYY-MM-DD')) SELECT media_type, count(*) FROM recentes GROUP BY media_type",
  "limit": 500
}

{
  "data": {
    "columns": [{ "name": "campaign", "type": "text" }],
    "rows": [["black-friday", 128]],
    "row_count": 1,
    "truncated": false,
    "elapsed_ms": 412
  }
}

truncated verdadeiro quer dizer que o servidor cortou no teto dele: você NÃO leu tudo. Os reason possíveis na recusa são nao_parseia, mais_de_um_statement, nao_e_select, schema_fora_do_escopo, tabela_sem_schema, funcao_fora_da_allowlist e cte_recursiva quando a guarda recusou a FORMA do SQL, e recusado_pelo_banco quando ele passou pela guarda e foi o Postgres que recusou — nome de coluna que não existe, tipo incompatível. E tempo_esgotado quando a consulta é pesada demais e o servidor a interrompeu. São três ações diferentes: mudar a construção, conferir nomes e tipos, ou reduzir o recorte — período menor, mais filtro, agregar antes. Indisponibilidade não aparece aqui: ela é 503, não traz reason, e nela retentar É o certo.

A resposta vem em data, como nas outras rotas. Por um tempo os mesmos campos saem também na raiz, para quem integrou antes; eles vão sair. Leia de data.

POST /api/v1/queries

Cria uma consulta no projeto, com a mesma guarda do SQL acima. A consulta fica sendo da PESSOA: o seu app entra como procedência, e é a procedência que decide o que ele pode editar depois. Guarde o id — é ele que as rotas de resultado e de atualização usam.

{
  "name": "Vendas por campanha",
  "sql": "SELECT …",
  "schedule": { "interval_minutes": 60, "enabled": true }
}

PATCH /api/v1/queries/{id}

Edita nome, SQL ou cadência. Só vale para consulta que o PRÓPRIO app criou. Qualquer outra responde 404, inclusive a que a pessoa escreveu na tela: dizer 403 revelaria que ela existe.

DELETE /api/v1/queries/{id}

Arquiva a consulta, não apaga. Vale a mesma regra de procedência do PATCH: o que o seu app não criou responde 404.

GET /api/v1/projects/{prj}/instagram/accounts

Parâmetros: limit, cursor. Ordem por id (o id da conta na Meta). Campo ausente significa que a Meta não informou — a resposta nunca inventa 0.

{
  "data": [
    {
      "id": "17840000000000000",
      "source_id": "00000000-0000-4000-8000-000000000002",
      "username": "exemplo_loja",
      "name": "Exemplo Loja",
      "biography": "Loja de exemplo. Atendimento de segunda a sexta.",
      "profile_picture_url": "https://…",
      "followers_count": 5000,
      "follows_count": 400,
      "media_count": 3000,
      "observed_at": "2026-09-16T11:04:12.318201+00:00"
    }
  ],
  "next_cursor": null
}

GET /api/v1/projects/{prj}/instagram/accounts/{ig_id}/media

Parâmetros: limit, cursor, since e until. Ordem: da mídia mais recente para a mais antiga (por timestamp, o instante da publicação na Meta).

curl "https://crazyleads.com.br/api/v1/projects/PRJ/instagram/accounts/17840000000000000/media?since=2026-09-01T00:00:00%2B0000&limit=50" \
  -H "Authorization: Bearer SEU_TOKEN_DE_ACESSO"

{
  "data": [
    {
      "id": "17890000000000000",
      "kind": "carousel",
      "media_type": "CAROUSEL_ALBUM",
      "media_product_type": "FEED",
      "timestamp": "2026-09-15T16:33:11+0000",
      "permalink": "https://www.instagram.com/p/…/",
      "thumbnail_url": "https://…",
      "media_url": "https://…",
      "like_count": 40,
      "comments_count": 3,
      "insights": {
        "reach": 500,
        "views": 1200,
        "likes": 40,
        "comments": 3,
        "saved": 12,
        "shares": 5,
        "total_interactions": 60
      },
      "observed_at": "2026-09-16T11:04:40.102938+00:00"
    }
  ],
  "next_cursor": "eyJrIjoi…"
}

GET /api/v1/projects/{prj}/instagram/accounts/{ig_id}/media/{media_id}/comments

Os comentários de uma mídia, cada um com as suas respostas. Escopo data:instagram:read. Ao contrário de contas e mídias, que saem do que o CrazyLeads já coletou, os comentários são lidos na hora, da Meta — por isso aqui limit vai de 1 a 50 (padrão 20), e a ordem é a que a Meta devolve. Parâmetros: limit e cursor; o cursor só vale para a mesma mídia.

curl "https://crazyleads.com.br/api/v1/projects/PRJ/instagram/accounts/17840000000000000/media/17890000000000000/comments?limit=20" \
  -H "Authorization: Bearer SEU_TOKEN_DE_ACESSO"

{
  "data": [
    {
      "id": "17900000000000001",
      "text": "Quando abre a próxima turma?",
      "username": "cliente_exemplo",
      "timestamp": "2026-09-22T14:03:11+0000",
      "like_count": 2,
      "hidden": false,
      "replies": [
        {
          "id": "17900000000000002",
          "text": "Semana que vem! Te chamo no direct.",
          "username": "exemplo_loja",
          "timestamp": "2026-09-22T14:10:40+0000",
          "like_count": 0,
          "hidden": false
        }
      ]
    }
  ],
  "next_cursor": "eyJrIjoi…"
}

A mídia tem de ser uma das que o CrazyLeads já coletou desta conta (as de …/media); outra qualquer é 404. Campo que a Meta não mandou não aparece, e replies vem sempre, vazio quando não há resposta.

POST /api/v1/projects/{prj}/instagram/accounts/{ig_id}/media/{media_id}/comments

Comenta numa mídia da própria conta, em nome dela. Escopo data:instagram:write. O corpo leva só message: texto de 1 a 2.200 caracteres, aparado nas pontas; outro campo é ignorado. O cabeçalho Idempotency-Key é obrigatório: sem ele, 400 (veja repetir sem comentar duas vezes).

curl -X POST "https://crazyleads.com.br/api/v1/projects/PRJ/instagram/accounts/17840000000000000/media/17890000000000000/comments" \
  -H "Authorization: Bearer SEU_TOKEN_DE_ACESSO" \
  -H "Idempotency-Key: 6f1c1d2e-7a8b-4c9d-8e0f-1a2b3c4d5e6f" \
  -H "Content-Type: application/json" \
  -d '{"message": "Obrigado por comentar! As inscrições abrem segunda."}'

{ "id": "17900000000000003" }

POST /api/v1/projects/{prj}/instagram/accounts/{ig_id}/comments/{comment_id}/replies

Responde a um comentário, em nome da conta. Mesmo escopo, mesmo corpo (message, de 1 a 2.200 caracteres) e a mesma Idempotency-Key obrigatória. A Meta não aninha mais de um nível: responder a uma resposta cai no mesmo fio.

curl -X POST "https://crazyleads.com.br/api/v1/projects/PRJ/instagram/accounts/17840000000000000/comments/17900000000000001/replies" \
  -H "Authorization: Bearer SEU_TOKEN_DE_ACESSO" \
  -H "Idempotency-Key: 0b7e2a3c-4d5e-4f60-8a9b-1c2d3e4f5a6b" \
  -H "Content-Type: application/json" \
  -d '{"message": "Semana que vem! Te chamo no direct."}'

{ "id": "17900000000000004" }

POST /api/v1/projects/{prj}/instagram/accounts/{ig_id}/comments/{comment_id}/hide

Oculta ({"hidden": true}) ou volta a mostrar ({"hidden": false}) um comentário. hidden é obrigatório e booleano: "true" em texto é 400. O comentário oculto some para o público, mas continua existindo e aparece na lista com "hidden": true.

{ "hidden": true }

{ "id": "17900000000000001", "hidden": true }

DELETE /api/v1/projects/{prj}/instagram/accounts/{ig_id}/comments/{comment_id}

Apaga o comentário na Meta, de vez: não há lixeira do lado do Instagram. Sem corpo.

{ "id": "17900000000000001", "deleted": true }

Moderação: o que não existe e o que pode dar errado

Repetir sem comentar duas vezes: Idempotency-Key

O cabeçalho Idempotency-Key é obrigatório para comentar e responder, e opcional para ocultar e apagar. Criar é publicar na rede da pessoa, e repetir sem chave publicaria duas vezes; ocultar e apagar só mudam o estado de um comentário, e repetir não duplica nada. Com a chave, a nova tentativa devolve a mesma resposta da primeira.

Mande uma chave nova por ação — um UUID serve — e, se a chamada estourar o tempo ou cair sem resposta, repita com a mesma chave e o mesmo corpo: se a primeira já tinha chegado, a resposta dela volta de novo e o comentário não é publicado duas vezes.

curl -X POST "https://crazyleads.com.br/api/v1/projects/PRJ/instagram/accounts/17840000000000000/comments/17900000000000001/hide" \
  -H "Authorization: Bearer SEU_TOKEN_DE_ACESSO" \
  -H "Idempotency-Key: 3c9d0e1f-2a3b-4c5d-8e6f-7a8b9c0d1e2f" \
  -H "Content-Type: application/json" \
  -d '{"hidden": true}'

GET /api/v1/queries

As consultas que a pessoa criou pela tela do CrazyLeads — sobre Instagram, Hotmart, pixel, qualquer fonte. Parâmetros: limit, cursor. É aqui que o seu app descobre o que dá para ler.

{
  "data": [
    {
      "id": "cmfk3x9a80001l204h8v2p7qz",
      "name": "Vendas por produto",
      "status": "ready",
      "has_result": true,
      "last_materialized_at": "2026-09-16T09:00:41.000Z",
      "row_count": 2631,
      "bytes": 184320
    }
  ],
  "next_cursor": null
}

GET /api/v1/queries/{id}/result

O resultado materializado de uma consulta. Dois formatos, escolhidos por format; o padrão é o Parquet, porque o caso de uso é montar uma área analítica, não iterar página. Formato desconhecido é 400. Consulta sem resultado ainda, ou de outro projeto, é 404.

curl "https://crazyleads.com.br/api/v1/queries/cmfk3x9a80001l204h8v2p7qz/result?format=parquet" \
  -H "Authorization: Bearer SEU_TOKEN_DE_ACESSO"

{
  "format": "parquet",
  "url": "https://…/….parquet?X-Amz-Algorithm=AWS4-HMAC-SHA256&…",
  "expires_at": "2026-09-16T12:15:00+00:00",
  "materialized_at": "2026-09-16T09:00:41+00:00",
  "row_count": 2631,
  "bytes": 184320
}

A url é assinada e vale 15 minutos; baixe na hora e não a guarde nem a repasse — quem a tiver, lê. Peça uma nova a cada download. materialized_at é o carimbo do arquivo: é ele que responde “de quando é este dado”.

curl "https://crazyleads.com.br/api/v1/queries/cmfk3x9a80001l204h8v2p7qz/result?format=json&limit=100" \
  -H "Authorization: Bearer SEU_TOKEN_DE_ACESSO"

{
  "format": "json",
  "materialized_at": "2026-09-16T09:00:41+00:00",
  "data": [
    { "produto": "Plano Anual", "vendas": 1830, "receita": 3641700.00 },
    { "produto": "Plano Mensal", "vendas": 801, "receita": 159399.00 }
  ],
  "next_cursor": "eyJrIjoi…"
}

O JSON pagina sobre o mesmo retrato do Parquet — nunca re-executa o SQL da pessoa. Se o resultado for materializado de novo no meio da sua paginação, a página seguinte responde 400 pedindo para recomeçar: é isso que garante que você nunca cola a página 3 do retrato novo na página 2 do antigo. As colunas são as que a pessoa escreveu na consulta.

POST /api/v1/queries/{id}/refresh

Sem corpo. Pede uma nova materialização pelo mesmo caminho que o botão “Atualizar agora” do produto. 202: aceito, acontece em segundo plano; acompanhe pelo status e last_materialized_at em GET /api/v1/queries.

{
  "accepted": true,
  "task": "3f4a5b6c7d8e9f0a1b2c3d4e5b0c1d2e",
  "materialized_at": "2026-09-16T09:00:41+00:00"
}

materialized_at é o carimbo do resultado atual, o que você continua lendo enquanto a nova rodada não termina; null se nunca houve um. Sujeito aos tetos de materialização — veja o 429.

GET /api/v1/datasets

Os datasets ativos do projeto. Parâmetros: limit, cursor.

{
  "data": [
    {
      "id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
      "slug": "produtos",
      "name": "Produtos",
      "description": "Catálogo com preço de tabela",
      "row_count": 118,
      "version": 3,
      "updated_at": "2026-09-10T18:22:05+00:00"
    }
  ],
  "next_cursor": null
}

row_count é a estimativa que o banco mantém para a tabela, não uma contagem feita na hora: pode ficar defasada logo depois de uma importação grande e sai null num dataset que ainda não foi medido. Para o número exato, percorra rows.

GET /api/v1/datasets/{id}/rows

As linhas, na ordem do id de cada uma. Parâmetros: limit, cursor. As colunas são as do schema publicado do dataset. Dataset de outro projeto é 404.

{
  "data": [
    { "id": "8f14e45f-ceea-467a-9e6b-1f0e8f0b5d21", "produto": "Plano Anual", "valor": 1990.00 },
    { "id": "a0b1c2d3-e4f5-4a6b-8c7d-9e0f1a2b3c4d", "produto": "Plano Mensal", "valor": 199.00 }
  ],
  "next_cursor": null
}

GET /api/v1/leads

Os leads do projeto, na ordem de updated_at e id. Parâmetros: limit, cursor e updated_since, um instante ISO 8601 COM fuso (sem fuso é 400). Use updated_since para buscar só o que mudou desde a última leitura: um lead alterado durante a paginação reaparece mais adiante, nunca some.

{
  "data": [
    {
      "id": "2f0c8a1e-6b1d-4c6e-9a51-3b7e9d0a1c22",
      "status": "active",
      "name": "Maria Souza",
      "email": "maria@exemplo.com.br",
      "phone": "+5561999990000",
      "is_identified": true,
      "created_at": "2026-09-01T10:00:00+00:00",
      "updated_at": "2026-09-18T10:00:00.123456+00:00"
    }
  ],
  "next_cursor": "eyJrIjoi…"
}

POST /api/v1/leads/search

Encontra um lead por {"email": "…"} OU {"phone": "+55…"}, sempre no corpo: na URL, o contato ficaria nos registros de todo proxy do caminho. Igualdade exata, sem curinga, até 10 leads; data vem vazio quando ninguém tem aquele contato. Mandar os dois, ou nenhum, é 400.

GET /api/v1/leads/{id}

Além dos campos da lista, emails e phones (cada um com value e is_primary), attributes (namespace, key, value: o valor mais recente de cada campo) e merged_into, preenchido quando o lead foi unido a outro.

GET /api/v1/leads/{id}/timeline

O que o lead fez, do mais recente ao mais antigo, com limit e cursor. Cada item tem occurred_at, type, source, utm, transaction e page_url. O amount da transação sai como TEXTO decimal, nunca como número arredondado.

GET /api/v1/lead-fields

Os campos personalizados de lead do projeto: id, key, name, type, mode e description. É o que explica as chaves que aparecem em attributes.

GET /api/v1/audiences

Cada público traz id, slug, name, status, realtime, members (o tamanho), published_at e rule. O status é um dos estados que a tela de Públicos mostra, com o mesmo nome: calculando, sem_destino, sincronizada, sincronizando, pausada, bloqueada, falha ou erro_de_calculo.

GET /api/v1/audiences/{id}

Os mesmos campos da lista, mais description.

GET /api/v1/audiences/{id}/members

Os membros são pessoas, então esta rota exige data:audiences:read e data:leads:read; sem o segundo, a resposta é 403. Cada membro tem os campos de um lead e mais entered_at.

GET /api/v1/envios

Cada item é o Envio como a tela de Envios o mostra: o id é o mesmo que a tela usa e não muda quando a pessoa edita o envio, e um Envio com vários destinos é um item só, com os destinos em destination_ids. Os campos são id, name, signal_type, destination_ids, enabled e created_at.

GET /api/v1/envios/{id}/stats

A estatística recebe period (7d, 14d, 30d ou 90d; padrão 30d) e devolve os totais sent, failed, dead e skipped, last_sent_at e daily, dia a dia. O dia da estatística é contado em UTC: o total bate com a tela, mas o corte de cada dia pode não bater com o horário de Brasília.

GET /api/v1/destinations

Os destinos do projeto: id, type, name, status e health. O config de um destino nunca sai: é nele que fica a credencial da ferramenta.

5. Erros, e o que fazer em cada caso

Todo erro da /v1 tem o mesmo envelope. Decida pelo code; a message é para gente ler e pode mudar.

{
  "error": {
    "code": "insufficient_scope",
    "message": "missing scope data:analytics:read",
    "request_id": "0b7e2a3c-4d5e-4f60-8a9b-1c2d3e4f5a6b"
  }
}

O 429: os tetos

Materializar e sincronizar custam — uma materialização pode varrer centenas de gigabytes do projeto da pessoa, e a conta é dela, não do seu app — e ler lead expõe dado pessoal. Por isso essas rotas têm tetos. Eles são disjuntores, não limite de produto: existem para que um laço de retry no seu app não esvazie a cota de um projeto nem copie a base inteira de uma vez.

{
  "error": {
    "reason": "intervalo_minimo",
    "retry_at": "2026-09-16T09:15:41+00:00",
    "limit": 15,
    "observed": 1,
    "code": "rate_limited",
    "message": "(frase para gente ler — ilustrativa, pode mudar; decida por reason)",
    "request_id": "…"
  }
}

{
  "error": {
    "reason": "teto_diario_de_syncs",
    "limit": 0,
    "observed": 0,
    "code": "rate_limited",
    "message": "(ilustrativa)",
    "request_id": "…"
  }
}

O dia dos tetos diários é contado em UTC: a cota vira às 21h no horário de Brasília, não à meia-noite. Os valores são ajustáveis pelo CrazyLeads, para todos os apps ou para um app específico, sem novo deploy — e um teto em zero é o jeito de bloquear uma operação de um app. O teto diário de linhas é conferido antes da leitura e contado depois dela, porque o número de linhas só se conhece quando a página volta; por isso o dia pode passar do teto em até uma página por chamada simultânea. Um 404 (id que não existe no projeto) também conta como leitura. Rotas de leitura fora desta tabela não têm teto anunciado, mas trate 429 como resposta possível em qualquer rota.

6. Revogar

A pessoa revoga o acesso do seu app em Preferências → Aplicativos conectados (/account), a qualquer momento e sem avisar você. Ao revogar, todos os tokens do par — o seu app e ela — são marcados revogados de uma vez: os de acesso e os de renovação, inclusive os já expirados. Do seu lado, o efeito é um só: a chamada seguinte falha com 401 invalid_token, e a renovação pelo refresh token responde 400 invalid_grant. Trate isso como estado normal, não como erro transitório: pare de chamar, marque a conexão como desfeita no seu produto e ofereça autorizar de novo. Não repita a chamada, não tente outro token da mesma cadeia — nenhum deles volta a valer.

Quando é o seu app que encerra a relação — a pessoa desconectou a conta no seu produto —, revogue você mesmo. Deixar token vivo depois que ela saiu é o tipo de coisa que aparece numa auditoria:

curl -X POST https://crazyleads.com.br/api/oauth/revoke \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d token=SEU_TOKEN_DE_RENOVACAO \
  -d token_type_hint=refresh_token \
  -d client_id=SEU_CLIENT_ID

Revogar o token de renovação derruba também todos os tokens de acesso emitidos por ele. A resposta é 200 sem corpo, inclusive para um token que já não valia. Há ainda o terceiro caminho: o CrazyLeads suspender o seu app — aí a resposta passa a ser 403 insufficient_scope, e ela volta a ser 200 se a homologação for restabelecida.