Exportar consentimentos

A API de exportação dá ao seu backend duas formas de extrair os registros de consentimento de um site em CSV: streaming síncrono para volumes até ~100k linhas, ou jobs assíncronos para volumes maiores. Ambas as rotas aceitam Authorization: Bearer sk-... e consomem 1 unidade da cota mensal por chamada (o feature consent_export está disponível a partir do plano Starter).

A funcionalidade consent_export é gerenciada server-side: contas Free recebem 403 plan_limit_exceeded ao chamar qualquer rota desta página.

Quando usar cada modo

Cenário	Endpoint	Resposta
Site com < 100k linhas	`GET /api/v1/sites/{siteId}/consents/export?format=csv`	`200` com `text/csv` em streaming
Site com > 100k linhas (auto)	mesma rota acima	`202` com `id` (vira async automaticamente)
Forçar async (qualquer volume)	mesma rota + `?async=true`	`202` com `id`
Sempre async, independente do tamanho	`POST /api/v1/sites/{siteId}/exports`	`202` com `id`

A trilha de auditoria (cap de 5 exports por período no plano Starter / ilimitado no Pro+) é compartilhada — não dá para burlar trocando de rota.

Modo síncrono (streaming CSV)

GET /api/v1/sites/{siteId}/consents/export?format=csv responde com Content-Type: text/csv; charset=utf-8, Content-Disposition: attachment; filename="consents-<domain>-<YYYYMMDD>.csv" e BOM UTF-8 no início (Excel abre sem perguntar encoding). A paginação por keyset mantém o uso de memória O(batch_size) mesmo em sites grandes — você pode salvar direto num arquivo. Colunas: consent_id, accepted, analytics, marketing, country, region, user_agent, policy_version, created_at.

SITE_ID=6b8b4567-327a-4d10-92a5-9e8c4f5a7d12
curl -L \
  -H "Authorization: Bearer $CONSENTFLY_API_KEY" \
  -o consents.csv \
  "https://www.consentfly.com.br/api/v1/sites/$SITE_ID/consents/export?format=csv"

import { writeFile } from "node:fs/promises";

const siteId = "6b8b4567-327a-4d10-92a5-9e8c4f5a7d12";
const res = await fetch(
  `https://www.consentfly.com.br/api/v1/sites/${siteId}/consents/export?format=csv`,
  { headers: { Authorization: `Bearer ${process.env.CONSENTFLY_API_KEY}` } }
);
await writeFile("consents.csv", Buffer.from(await res.arrayBuffer()));

import os, requests

site_id = "6b8b4567-327a-4d10-92a5-9e8c4f5a7d12"
with requests.get(
    f"https://www.consentfly.com.br/api/v1/sites/{site_id}/consents/export",
    headers={"Authorization": f"Bearer {os.environ['CONSENTFLY_API_KEY']}"},
    params={"format": "csv"},
    stream=True,
) as res:
    with open("consents.csv", "wb") as f:
        for chunk in res.iter_content(chunk_size=8192):
            f.write(chunk)

siteID := "6b8b4567-327a-4d10-92a5-9e8c4f5a7d12"
url := "https://www.consentfly.com.br/api/v1/sites/" + siteID + "/consents/export?format=csv"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("CONSENTFLY_API_KEY"))
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
f, _ := os.Create("consents.csv")
defer f.Close()
io.Copy(f, res.Body)

Modo assíncrono (enqueue + status + download)

Quando o site cruza ~100k linhas (ou quando você força com ?async=true), a mesma rota responde 202 Accepted. Para sempre enfileirar (independente do tamanho), use POST /api/v1/sites/{siteId}/exports.

Enfileirar um export

SITE_ID=6b8b4567-327a-4d10-92a5-9e8c4f5a7d12
curl -X POST \
  -H "Authorization: Bearer $CONSENTFLY_API_KEY" \
  "https://www.consentfly.com.br/api/v1/sites/$SITE_ID/exports"

const siteId = "6b8b4567-327a-4d10-92a5-9e8c4f5a7d12";
const res = await fetch(
  `https://www.consentfly.com.br/api/v1/sites/${siteId}/exports`,
  { method: "POST", headers: { Authorization: `Bearer ${process.env.CONSENTFLY_API_KEY}` } }
);
const { id, status_url } = await res.json();

import os, requests

site_id = "6b8b4567-327a-4d10-92a5-9e8c4f5a7d12"
res = requests.post(
    f"https://www.consentfly.com.br/api/v1/sites/{site_id}/exports",
    headers={"Authorization": f"Bearer {os.environ['CONSENTFLY_API_KEY']}"},
)
job = res.json()  # { id, status: "queued", status_url, message }

siteID := "6b8b4567-327a-4d10-92a5-9e8c4f5a7d12"
url := "https://www.consentfly.com.br/api/v1/sites/" + siteID + "/exports"
req, _ := http.NewRequest("POST", url, nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("CONSENTFLY_API_KEY"))
http.DefaultClient.Do(req)

A resposta 202 traz id (use-o para polling), status: "queued", e status_url para consulta.

Consultar status do job

GET /api/v1/exports/{id} devolve o ExportDTO com o status atual. Quando status="ready", o campo download_url é uma URL assinada com TTL de 10 minutos.

curl https://www.consentfly.com.br/api/v1/exports/exp_01HK8WD2QXKB4R7N9F1H3P5T0G \
  -H "Authorization: Bearer $CONSENTFLY_API_KEY"

const exportId = "exp_01HK8WD2QXKB4R7N9F1H3P5T0G";
const res = await fetch(`https://www.consentfly.com.br/api/v1/exports/${exportId}`, {
  headers: { Authorization: `Bearer ${process.env.CONSENTFLY_API_KEY}` },
});
const job = await res.json();

import os, requests

export_id = "exp_01HK8WD2QXKB4R7N9F1H3P5T0G"
res = requests.get(
    f"https://www.consentfly.com.br/api/v1/exports/{export_id}",
    headers={"Authorization": f"Bearer {os.environ['CONSENTFLY_API_KEY']}"},
)
job = res.json()

exportID := "exp_01HK8WD2QXKB4R7N9F1H3P5T0G"
req, _ := http.NewRequest("GET", "https://www.consentfly.com.br/api/v1/exports/"+exportID, nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("CONSENTFLY_API_KEY"))
http.DefaultClient.Do(req)

Baixar o arquivo pronto

GET /api/v1/exports/{id}/download retorna um 302 para uma URL assinada (TTL 10 min). Use -L no cURL para seguir o redirect. Se o token expirar, basta chamar GET /exports/{id} de novo — uma URL fresca é mintada a cada chamada.

curl -L \
  -H "Authorization: Bearer $CONSENTFLY_API_KEY" \
  -o consents.csv \
  "https://www.consentfly.com.br/api/v1/exports/exp_01HK8WD2QXKB4R7N9F1H3P5T0G/download"

import { writeFile } from "node:fs/promises";

const exportId = "exp_01HK8WD2QXKB4R7N9F1H3P5T0G";
const res = await fetch(
  `https://www.consentfly.com.br/api/v1/exports/${exportId}/download`,
  { headers: { Authorization: `Bearer ${process.env.CONSENTFLY_API_KEY}` }, redirect: "follow" }
);
await writeFile("consents.csv", Buffer.from(await res.arrayBuffer()));

import os, requests

export_id = "exp_01HK8WD2QXKB4R7N9F1H3P5T0G"
with requests.get(
    f"https://www.consentfly.com.br/api/v1/exports/{export_id}/download",
    headers={"Authorization": f"Bearer {os.environ['CONSENTFLY_API_KEY']}"},
    allow_redirects=True,
    stream=True,
) as res:
    with open("consents.csv", "wb") as f:
        for chunk in res.iter_content(chunk_size=8192):
            f.write(chunk)

exportID := "exp_01HK8WD2QXKB4R7N9F1H3P5T0G"
url := "https://www.consentfly.com.br/api/v1/exports/" + exportID + "/download"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("CONSENTFLY_API_KEY"))
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
f, _ := os.Create("consents.csv")
defer f.Close()
io.Copy(f, res.Body)

Estados possíveis

Status	Significado
`queued`	Esperando o worker pegar
`running`	Worker está escrevendo o arquivo
`ready`	Arquivo pronto, `download_url` disponível
`failed`	Falha durante a escrita — `error_message` traz o detalhe
`expired`	Passados 7 dias, o cron de limpeza removeu o arquivo do disco
`streamed`	Foi servido inline (modo síncrono) — sem arquivo persistente

Listar seus exports recentes

GET /api/v1/exports?limit=20 retorna os exports mais recentes (máximo 100 por chamada).

curl "https://www.consentfly.com.br/api/v1/exports?limit=20" \
  -H "Authorization: Bearer $CONSENTFLY_API_KEY"

const res = await fetch("https://www.consentfly.com.br/api/v1/exports?limit=20", {
  headers: { Authorization: `Bearer ${process.env.CONSENTFLY_API_KEY}` },
});
const { data } = await res.json();

import os, requests

res = requests.get(
    "https://www.consentfly.com.br/api/v1/exports",
    headers={"Authorization": f"Bearer {os.environ['CONSENTFLY_API_KEY']}"},
    params={"limit": 20},
)
exports = res.json()["data"]

req, _ := http.NewRequest("GET", "https://www.consentfly.com.br/api/v1/exports?limit=20", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("CONSENTFLY_API_KEY"))
http.DefaultClient.Do(req)

Limites e retenção

Cota mensal: cada chamada API-key conta 1 unidade contra request_limit.
Cap por período de cobrança: Starter 5 exports / período, Pro+ ilimitado.
Retenção em disco: arquivos ready vivem 7 dias; depois flipam para expired e o download retorna 410 Gone.
Cross-tenant: chamadas para ids que não pertencem à sua conta retornam 404 (nunca 403, para não vazar existência).

Erros frequentes

Código HTTP	`error`	Quando
`401`	`unauthorized`	API Key inválida, revogada ou token de download expirado
`403`	`plan_limit_exceeded`	Plano Free tentando usar `consent_export`
`404`	`not_found`	Export ou site não pertence à sua conta
`409`	`conflict`	Tentou baixar um export ainda em `queued`/`running`/`failed`
`410`	`not_found`	Arquivo foi expurgado (passados os 7 dias)
`429`	`quota_exceeded`	Cota mensal esgotada ou cap de exports do período atingido

Próximo passo

Exports cobrem o passado: você pega os dados que já estão armazenados. Para reagir a eventos em tempo real (todo novo consentimento, toda mudança), configure Webhooks — o ConsentFly empurra o evento assinado para o seu endpoint assim que acontece, e seu pipeline fica sempre sincronizado sem polling.

Dúvidas? suporte@consentfly.com.br

Introdução

Guias da API

Exportar consentimentos

Quando usar cada modo

Modo síncrono (streaming CSV)

Modo assíncrono (enqueue + status + download)

Enfileirar um export

Consultar status do job

Baixar o arquivo pronto

Estados possíveis

Listar seus exports recentes

Limites e retenção

Erros frequentes

Próximo passo

​Quando usar cada modo

​Modo síncrono (streaming CSV)

​Modo assíncrono (enqueue + status + download)

​Enfileirar um export

​Consultar status do job

​Baixar o arquivo pronto

​Estados possíveis

​Listar seus exports recentes

​Limites e retenção

​Erros frequentes

​Próximo passo

Quando usar cada modo

Modo síncrono (streaming CSV)

Modo assíncrono (enqueue + status + download)

Enfileirar um export

Consultar status do job

Baixar o arquivo pronto

Estados possíveis

Listar seus exports recentes

Limites e retenção

Erros frequentes

Próximo passo