ProsalabDevelopers
Entrar no app

Campanhas

Liste campanhas, acompanhe métricas de entrega, adicione destinatários e controle o ciclo de vida (iniciar, pausar, retomar). Alguns endpoints (adicionar destinatários e relatório consolidado) exigem plano Enterprise.

GET/api/v1/campaigns
escopo: campaigns:read

Lista as campanhas da empresa. Filtro: ?status=draft,sending

Resposta (200)

Corpo da resposta
{
  "success": true,
  "data": [
    {
      "id": "<uuid>",
      "name": "Promoção de Julho",
      "status": "sending",
      "type": "promotional",
      "total_recipients": 100,
      "messages_sent": 40,
      "messages_delivered": 38,
      "messages_failed": 1,
      "messages_replied": 5,
      "created_at": "2026-07-10T10:00:00.000Z",
      "started_at": "2026-07-10T10:05:00.000Z",
      "completed_at": null
    }
  ]
}

Exemplo

curl
curl -s -H "Authorization: Bearer <sua-key>" https://www.prosalab.com/api/v1/campaigns
GET/api/v1/campaigns/{id}
escopo: campaigns:read

Status e métricas de entrega de uma campanha.

Resposta (200)

Corpo da resposta
{
  "success": true,
  "data": {
    "id": "<uuid>",
    "name": "Promoção de Julho",
    "status": "sending",
    "type": "promotional",
    "total_recipients": 100,
    "messages_sent": 90,
    "messages_delivered": 85,
    "messages_read": 50,
    "messages_failed": 2,
    "messages_replied": 10,
    "estimated_cost_usd": 4.5,
    "actual_cost_usd": 3.9,
    "created_at": "2026-07-10T10:00:00.000Z",
    "started_at": "2026-07-10T10:05:00.000Z",
    "completed_at": null,
    "paused_at": null,
    "cancelled_at": null,
    "delivery_rate": 0.94,
    "read_rate": 0.55,
    "reply_rate": 0.11
  }
}

Erros

StatusCódigoQuando ocorre
404NOT_FOUNDCampanha não existe ou pertence a outra empresa
500PROVIDER_ERRORErro interno — esta família de rotas (legada) usa o código PROVIDER_ERROR no 500

Exemplo

curl
curl -s -H "Authorization: Bearer <sua-key>" https://www.prosalab.com/api/v1/campaigns/{id}
POST/api/v1/campaigns/{id}/start
escopo: campaigns:write

Inicia uma campanha em rascunho.

Resposta (200)

Corpo da resposta
{
  "success": true,
  "data": {
    "campaign_id": "<uuid>",
    "status": "sending",
    "total_recipients": 100
  }
}

Erros

StatusCódigoQuando ocorre
404NOT_FOUNDCampanha não existe ou pertence a outra empresa
400INVALID_STATUSCampanha não está em rascunho (draft)
400MISSING_FIELDCampanha sem produto vinculado ou sem destinatários
500PROVIDER_ERRORErro interno — esta família de rotas (legada) usa o código PROVIDER_ERROR no 500

Exemplo

curl
curl -s -X POST -H "Authorization: Bearer <sua-key>" https://www.prosalab.com/api/v1/campaigns/{id}/start
POST/api/v1/campaigns/{id}/pause
escopo: campaigns:write

Pausa uma campanha em envio.

Resposta (200)

Corpo da resposta
{
  "success": true,
  "data": {
    "campaign_id": "<uuid>",
    "status": "paused"
  }
}

Erros

StatusCódigoQuando ocorre
404NOT_FOUNDCampanha não existe ou pertence a outra empresa
400INVALID_STATUSCampanha não está em envio (sending)
500PROVIDER_ERRORErro interno — esta família de rotas (legada) usa o código PROVIDER_ERROR no 500

Exemplo

curl
curl -s -X POST -H "Authorization: Bearer <sua-key>" https://www.prosalab.com/api/v1/campaigns/{id}/pause
POST/api/v1/campaigns/{id}/resume
escopo: campaigns:write

Retoma uma campanha pausada.

Resposta (200)

Corpo da resposta
{
  "success": true,
  "data": {
    "campaign_id": "<uuid>",
    "status": "sending"
  }
}

Erros

StatusCódigoQuando ocorre
404NOT_FOUNDCampanha não existe ou pertence a outra empresa
400INVALID_STATUSCampanha não está pausada
500PROVIDER_ERRORErro interno — esta família de rotas (legada) usa o código PROVIDER_ERROR no 500

Exemplo

curl
curl -s -X POST -H "Authorization: Bearer <sua-key>" https://www.prosalab.com/api/v1/campaigns/{id}/resume
GET/api/v1/campaigns/{id}/recipients
escopo: campaigns:read

Lista paginada de destinatários. Parâmetros: ?page=1&limit=50&status=sent

Resposta (200)

Corpo da resposta
{
  "success": true,
  "data": [
    {
      "id": "<uuid>",
      "status": "sent",
      "scheduled_send_at": "2026-07-10T10:05:00.000Z",
      "attempt_count": 1,
      "sent_at": "2026-07-10T10:06:00.000Z",
      "delivered_at": "2026-07-10T10:06:05.000Z",
      "read_at": null,
      "failure_reason": null,
      "contact_name": "João Silva",
      "contact_phone": "5548999990000"
    }
  ],
  "total": 100,
  "page": 1,
  "limit": 50
}

Erros

StatusCódigoQuando ocorre
404NOT_FOUNDCampanha não existe ou pertence a outra empresa

Exemplo

curl
curl -s -H "Authorization: Bearer <sua-key>" https://www.prosalab.com/api/v1/campaigns/{id}/recipients
POST/api/v1/campaigns/{id}/recipients
escopo: campaigns:writeEnterprise

Adiciona destinatários a uma campanha em rascunho/agendada (por contact_ids e/ou por telefone; máx. 100 por chamada).

  • Informe ao menos um contact_id ou um contato por telefone; o total combinado deve ser ≤ 100.

Modelo de envio

Corpo da requisição
{
  "contact_ids": [
    "<uuid>"
  ],
  "contacts": [
    {
      "phone": "5548999990000",
      "name": "João Silva"
    }
  ]
}

Resposta (200)

Corpo da resposta
{
  "success": true,
  "data": {
    "added": 5,
    "skipped_blocked": 0,
    "skipped_opted_out": 1,
    "already_present": 2,
    "not_found": 0,
    "total_recipients": 105
  }
}

Erros

StatusCódigoQuando ocorre
404NOT_FOUNDCampanha não existe ou pertence a outra empresa
409CAMPAIGN_LOCKEDCampanha fora de draft/scheduled (inclui scheduled já vencido) — retorna o "status" atual

Exemplo

curl
curl -s -X POST -H "Authorization: Bearer <sua-key>" -H "Content-Type: application/json" \
  -d '{"contact_ids":["<uuid>"],"contacts":[{"phone":"5548999990000","name":"João Silva"}]}' \
  https://www.prosalab.com/api/v1/campaigns/{id}/recipients
GET/api/v1/campaigns/{id}/report
escopo: campaigns:readEnterprise

Relatório consolidado: métricas, taxas e breakdown por status de destinatário.

Resposta (200)

Corpo da resposta
{
  "success": true,
  "data": {
    "campaign": {
      "id": "<uuid>",
      "name": "Promoção de Julho",
      "status": "sending",
      "created_at": "2026-07-10T10:00:00.000Z",
      "started_at": "2026-07-10T10:05:00.000Z",
      "completed_at": null
    },
    "metrics": {
      "recipients": 100,
      "sent": 90,
      "delivered": 85,
      "read": 50,
      "replied": 10,
      "failed": 2,
      "delivery_rate": 0.94,
      "read_rate": 0.55,
      "reply_rate": 0.11
    },
    "recipients_by_status": [
      {
        "status": "sent",
        "count": 90
      }
    ]
  }
}

Erros

StatusCódigoQuando ocorre
404NOT_FOUNDCampanha não existe ou pertence a outra empresa

Exemplo

curl
curl -s -H "Authorization: Bearer <sua-key>" https://www.prosalab.com/api/v1/campaigns/{id}/report
POST/api/v1/campaigns/{id}/send
escopo: campaigns:write

Adiciona contatos (por nome e telefone) e inicia a campanha em um único request.

Modelo de envio

Corpo da requisição
{
  "contacts": [
    {
      "name": "João Silva",
      "phone": "5548999990000"
    }
  ]
}

Resposta (200)

Corpo da resposta
{
  "success": true,
  "data": {
    "campaign_id": "<uuid>",
    "campaign_status": "sending",
    "total_recipients": 105,
    "imported": 5,
    "skipped": 0,
    "errors": []
  }
}

Erros

StatusCódigoQuando ocorre
404NOT_FOUNDCampanha não existe ou pertence a outra empresa
400INVALID_STATUSCampanha cancelada ou com falha
400MISSING_FIELDSem produto vinculado, sem contatos válidos ou lote > 100
500PROVIDER_ERRORErro interno — esta família de rotas (legada) usa o código PROVIDER_ERROR no 500

Exemplo

curl
curl -s -X POST -H "Authorization: Bearer <sua-key>" -H "Content-Type: application/json" \
  -d '{"contacts":[{"name":"João Silva","phone":"5548999990000"}]}' \
  https://www.prosalab.com/api/v1/campaigns/{id}/send
Campanhas — Prosalab Developers