API v2 com OAuth

A nova versão da API Oblic trabalha com os objetos visíveis no Oblic, jornadas, segmentos e mensagens, no espaço conectado por uma pessoa. Usa tokens de acesso OAuth 2.1 em vez de chaves de API e atua com o papel dessa pessoa. /external/v1 continua funcionando com suas chaves de API.


Obter um token

A API v2 nunca aceita uma chave de API: enviá-la retorna 401 API_KEY_NOT_ACCEPTED. Uma pessoa conecta seu aplicativo a um dos espaços dela, onde ele atua em seu nome.

A implantação Oblic precisa ter o servidor de autorização OAuth habilitado, a API v2 entre os recursos permitidos, chaves de assinatura e página de consentimento configuradas e seu cliente registrado. Confirme a disponibilidade com o suporte Oblic antes de integrar; as URLs de exemplo não comprovam que uma implantação esteja configurada.

  1. Registre seu aplicativo. Informe ao suporte Oblic o nome, as URIs de redirecionamento e os escopos necessários para receber um identificador de cliente. Os clientes são públicos: não há segredo de cliente e toda autorização usa PKCE. Somente um servidor ou aplicativo nativo pode usar a API: nenhuma origem de navegador é permitida no endpoint de tokens nem na API.
  2. Peça à pessoa que entre. Abra o endpoint de autorização com o resource da API v2 e scope=read send para enviar mensagens, ou scope=read apenas para leitura. A pessoa entra no Oblic, escolhe o espaço e aprova os escopos.
  3. Troque o código no endpoint de tokens com o mesmo resource.
  4. Chame a API com Authorization: Bearer <access token>.
Servidor de autorizaçãohttps://api.oblic.app (metadados em /.well-known/oauth-authorization-server)
Endpoint de autorizaçãohttps://api.oblic.app/oauth2/authorize
Endpoint de tokenshttps://api.oblic.app/oauth2/token
Recursohttps://api.oblic.app/external/v2
PKCESomente S256
Token de acessoválido por uma hora por padrão
Token de atualizaçãosubstituído a cada uso; por padrão expira após 30 dias sem uso e 90 dias após a conexão inicial

Trocar o código

curl -X POST https://api.oblic.app/oauth2/token \
  -d grant_type=authorization_code \
  -d client_id=YOUR_CLIENT_ID \
  -d code=THE_CODE \
  -d redirect_uri=https://app.example.com/callback \
  -d code_verifier=YOUR_CODE_VERIFIER \
  -d resource=https://api.oblic.app/external/v2

Um token emitido para outro recurso, como o servidor MCP do Oblic, não funciona aqui. Uma solicitação sem token utilizável recebe 401 com o cabeçalho WWW-Authenticate apontando os metadados do recurso, https://api.oblic.app/.well-known/oauth-protected-resource/external/v2.

Escopos e papéis

  • Nome
    read
    Tipo
    scope
    Descrição

    Solicite-o sempre: um token sem esse escopo é recusado. Permite ler jornadas e segmentos do espaço e mensagens enviadas pela API.

  • Nome
    send
    Tipo
    scope
    Descrição

    Permite enfileirar envios de e-mail, SMS e WhatsApp pela organização; não significa que o provedor os entregou. Esse escopo aparece em uma linha separada antes da aprovação.

Um escopo nunca excede o papel da pessoa, verificado em cada solicitação. Retirar o papel ou remover a pessoa da organização interrompe imediatamente o acesso do token.

  • Jornadas e segmentos pertencem ao espaço escolhido pela pessoa; qualquer papel nesse espaço permite lê-los.
  • Mensagens enviadas pela API pertencem ao espaço padrão da organização, como ocorre com uma chave de API. Enviar exige send e o papel Owner, Admin ou Editor nesse espaço; qualquer papel ali permite ler.

O token não está sujeito à lista de IPs permitidos da organização para chaves de API: ele é usado nos servidores do aplicativo e limitado pelo papel da pessoa e pelos escopos aprovados.


Endpoints da API

Cada resposta contém {"status": "success", "data": …, "errors": null}, ou "status": "error" com os erros.

MétodoCaminhoFunção
GET/external/v2/journeysCampanhas, automações, bots do WhatsApp e jornadas criadas no Journeys do espaço, modificadas mais recentemente primeiro
GET/external/v2/journeys/{id}Uma jornada
GET/external/v2/segmentsListas do espaço, seguidas dos segmentos dinâmicos
GET/external/v2/segments/{id}Um segmento
POST/external/v2/messages/emailEnvia um e-mail de um remetente verificado
POST/external/v2/messages/smsEnvia um SMS correspondente a um de seus modelos DLT
POST/external/v2/messages/whatsappEnvia um modelo do WhatsApp aprovado ou uma resposta em até 24 horas
GET/external/v2/messagesMensagens enviadas pela API, mais recentes primeiro, com os parâmetros da lista v1
GET/external/v2/messages/{messageId}Uma mensagem enviada pela API e seu resultado

Listar jornadas

  • Nome
    offset
    Tipo
    integer
    Descrição

    Início da página; 0 por padrão.

  • Nome
    limit
    Tipo
    integer
    Descrição

    Quantidade de jornadas, de 1 a 100; 50 por padrão.

  • Nome
    mode
    Tipo
    string
    Descrição

    campaign, automation, bot ou journey para uma jornada criada no Journeys.

  • Nome
    status
    Tipo
    string
    Descrição

    Estados permitidos: draft, scheduled, live, paused ou done.

  • Nome
    search
    Tipo
    string
    Descrição

    Parte do nome de uma jornada.

O nextOffset indica o início da próxima página e é null na última.

Listar jornadas

curl 'https://api.oblic.app/external/v2/journeys?status=live&limit=20' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Resposta

{
  "status": "success",
  "data": {
    "journeys": [
      {
        "id": "CMP000R7ZM4Q2VXH00",
        "mode": "campaign",
        "name": "Weekly offer",
        "status": "live",
        "createdAt": "2026-10-01T09:30:00Z",
        "updatedAt": "2026-10-12T14:05:00Z"
      }
    ],
    "nextOffset": null
  },
  "errors": null
}

Enviar uma mensagem

Os corpos são os de /external/v1/messages. O envio entra na fila e recebe 202 com o identificador da mensagem. Repita com o mesmo cabeçalho Idempotency-Key, de 1 a 255 caracteres, como nos envios v1: o mesmo envio devolve o primeiro identificador sem reenviar; a mesma chave com outra mensagem recebe 409 IDEMPOTENCY_CONFLICT. A chave pertence ao seu aplicativo: outro aplicativo ou uma chave de API com o mesmo valor envia sua própria mensagem.

Enviar um e-mail

curl -X POST https://api.oblic.app/external/v2/messages/email \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-4471-shipped' \
  -d '{
    "to": ["customer@example.com"],
    "subject": "Your order has shipped",
    "html": "<p>Your order 4471 is on its way.</p>"
  }'

Resposta

{
  "status": "success",
  "data": { "id": "msg_4f9c2a7e1b8d4e0f9a6c3b2d1e0f9a8b", "status": "queued" },
  "errors": null
}

Consulte o resultado com GET /external/v2/messages/{messageId}.


Erros da API

Estado HTTPCódigo do erroSignificado
401MISSING_ACCESS_TOKENNenhum token de acesso enviado
401INVALID_ACCESS_TOKENToken expirado, emitido para outro recurso, sem read ou cuja pessoa saiu da organização: atualize-o ou conecte novamente
401API_KEY_NOT_ACCEPTEDChave de API enviada: use-a com /external/v1
403INSUFFICIENT_SCOPEEscopo necessário ausente, indicado em WWW-Authenticate: conecte novamente e aprove-o
403FORBIDDENO papel da pessoa não permite a operação
403EMAIL_SUSPENDEDE-mail da conta suspenso por devoluções ou denúncias de spam, como em /external/v1
400BAD_REQUEST, INVALID_IDEMPOTENCY_KEYParâmetro, cabeçalho ou corpo ausente ou ilegível
400nome do campo, como TOUm campo do corpo não é válido
402INSUFFICIENT_BALANCESMS ou WhatsApp de marketing exige saldo na carteira pagadora; carteira vazia não recusa códigos de acesso, mensagens transacionais nem respostas
404JOURNEY_NOT_FOUND, SEGMENT_NOT_FOUND, MESSAGE_NOT_FOUNDNão está no espaço ou não foi enviado pela API
404NOT_FOUNDEssa rota não existe
405METHOD_NOT_ALLOWEDA rota não aceita o método; Allow lista os permitidos
415UNSUPPORTED_MEDIA_TYPECorpo não enviado como application/json
422UNVERIFIED_SENDERRemetente do e-mail não verificado
429RATE_LIMITED, QUOTA_EXCEEDEDLimites horários ou cota mensal de e-mail excedidos, como em /external/v1; Retry-After informa quando tentar novamente

Um SMS ou WhatsApp também pode ser recusado por um motivo específico, como em /external/v1: modelo não aprovado, número que cancelou marketing, número não conectado ou limite atingido, com Retry-After quando convém tentar mais tarde.

Esta página foi útil?