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.
O documento OpenAPI desta versão é external-v2.json, apresentado como versão 2 na referência OpenAPI.
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.
- 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.
- Peça à pessoa que entre. Abra o endpoint de autorização com o
resourceda API v2 escope=read sendpara enviar mensagens, ouscope=readapenas para leitura. A pessoa entra no Oblic, escolhe o espaço e aprova os escopos. - Troque o código no endpoint de tokens com o mesmo
resource. - Chame a API com
Authorization: Bearer <access token>.
| Servidor de autorização | https://api.oblic.app (metadados em /.well-known/oauth-authorization-server) |
| Endpoint de autorização | https://api.oblic.app/oauth2/authorize |
| Endpoint de tokens | https://api.oblic.app/oauth2/token |
| Recurso | https://api.oblic.app/external/v2 |
| PKCE | Somente S256 |
| Token de acesso | válido por uma hora por padrão |
| Token de atualização | substituí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
sende 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étodo | Caminho | Função |
|---|---|---|
GET | /external/v2/journeys | Campanhas, 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/segments | Listas do espaço, seguidas dos segmentos dinâmicos |
GET | /external/v2/segments/{id} | Um segmento |
POST | /external/v2/messages/email | Envia um e-mail de um remetente verificado |
POST | /external/v2/messages/sms | Envia um SMS correspondente a um de seus modelos DLT |
POST | /external/v2/messages/whatsapp | Envia um modelo do WhatsApp aprovado ou uma resposta em até 24 horas |
GET | /external/v2/messages | Mensagens 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;
0por padrão.
- Nome
limit- Tipo
- integer
- Descrição
Quantidade de jornadas, de 1 a 100;
50por padrão.
- Nome
mode- Tipo
- string
- Descrição
campaign,automation,botoujourneypara uma jornada criada no Journeys.
- Nome
status- Tipo
- string
- Descrição
Estados permitidos:
draft,scheduled,live,pausedoudone.
- 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 HTTP | Código do erro | Significado |
|---|---|---|
| 401 | MISSING_ACCESS_TOKEN | Nenhum token de acesso enviado |
| 401 | INVALID_ACCESS_TOKEN | Token expirado, emitido para outro recurso, sem read ou cuja pessoa saiu da organização: atualize-o ou conecte novamente |
| 401 | API_KEY_NOT_ACCEPTED | Chave de API enviada: use-a com /external/v1 |
| 403 | INSUFFICIENT_SCOPE | Escopo necessário ausente, indicado em WWW-Authenticate: conecte novamente e aprove-o |
| 403 | FORBIDDEN | O papel da pessoa não permite a operação |
| 403 | EMAIL_SUSPENDED | E-mail da conta suspenso por devoluções ou denúncias de spam, como em /external/v1 |
| 400 | BAD_REQUEST, INVALID_IDEMPOTENCY_KEY | Parâmetro, cabeçalho ou corpo ausente ou ilegível |
| 400 | nome do campo, como TO | Um campo do corpo não é válido |
| 402 | INSUFFICIENT_BALANCE | SMS ou WhatsApp de marketing exige saldo na carteira pagadora; carteira vazia não recusa códigos de acesso, mensagens transacionais nem respostas |
| 404 | JOURNEY_NOT_FOUND, SEGMENT_NOT_FOUND, MESSAGE_NOT_FOUND | Não está no espaço ou não foi enviado pela API |
| 404 | NOT_FOUND | Essa rota não existe |
| 405 | METHOD_NOT_ALLOWED | A rota não aceita o método; Allow lista os permitidos |
| 415 | UNSUPPORTED_MEDIA_TYPE | Corpo não enviado como application/json |
| 422 | UNVERIFIED_SENDER | Remetente do e-mail não verificado |
| 429 | RATE_LIMITED, QUOTA_EXCEEDED | Limites 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.