API para ligar o seu sistema

Referência técnica

Guia técnico para programadores de integrações

Comece pelas convenções de chamada comuns e pelo início de sessão. Siga depois o processo desde o carregamento de um ficheiro até ao início de uma campanha e consulte os endpoints disponíveis.

Início de sessão

O identificador de início de sessão não é um endereço de e-mail, mas um código de oito caracteres gerado quando o utilizador é criado, por exemplo A1B2C3D4. Crie um utilizador dedicado com as permissões mínimas necessárias para a integração; o acesso poderá ser revogado a qualquer momento sem afetar outros utilizadores.

curl -u "A1B2C3D4:your-password" https://admin.example.org/api/public/login

A palavra-passe é enviada em cada pedido. Guarde-a como um segredo, por exemplo, numa variável de ambiente ou num cofre de palavras-passe; nunca no código-fonte, num repositório ou nos registos.

Os exemplos seguintes pressupõem que estas variáveis estão definidas:

export API="https://admin.example.org"
export AUTH="A1B2C3D4:a-sua-palavra-passe"

Os exemplos utilizam curl por não depender de uma linguagem de programação. A interface utiliza HTTP, pelo que pode ser chamada a partir de qualquer linguagem ou ferramenta que suporte Basic Auth, como Python, JavaScript, PHP, Postman ou Make.

Processo: de um ficheiro a uma campanha em reprodução

1. Obter o identificador da empresa. Será utilizado em todas as chamadas seguintes.
2. Carregar um ficheiro multimédia. A resposta devolve o respetivo identificador.
3. Carregar um modelo de campanha. O servidor preenche-o com as definições da empresa e a lista de locais e dispositivos.
4. Editar o modelo : nome, período, dispositivos de destino e visual.
5. Criar a campanha. É criada como rascunho e ainda não é reproduzida.
6. Ativar a campanha. O sistema prepara um novo plano de reprodução e envia-o para os dispositivos.
7. Acompanhar os resultados no relatório da campanha.

1. Identificador da empresa

curl -u "$AUTH" "$API/api/public/login"

Resposta abreviada:

{
  "id": 1715714421868,
  "name": "Integração – loja online",
  "login": "A1B2C3D4",
  "company": { "id": 1698234512001, "name": "Agência publicitária Lda." },
  "permission": {
    "resource": 12,
    "device_layer_top": 12,
    "report_layer_top": 4
  }
}

Guarde o valor de company.id; os exemplos utilizam-no na variável COMPANY. A secção permission lista as permissões do utilizador; o respetivo significado é descrito em Permissões.

2. Carregamento de um ficheiro multimédia

O ficheiro é enviado como corpo binário do pedido através de PUT; as suas propriedades são indicadas nos cabeçalhos.

curl -u "$AUTH" -X PUT \
  "$API/api/resource/single/$COMPANY" \
  -H "file-type: IMAGE" \
  -H "file-mime: image/jpeg" \
  -H "file-name: promocao-verao.jpg" \
  -H "file-suffix: jpg" \
  --data-binary @promocao-verao.jpg

A mesma chamada em Python:

import requests

with open("promocao-verao.jpg", "rb") as f:
    r = requests.put(
        f"{API}/api/resource/single/{COMPANY}",
        auth=("A1B2C3D4", "a-sua-palavra-passe"),
        headers={
            "file-type": "IMAGE",
            "file-mime": "image/jpeg",
            "file-name": "promocao-verao.jpg",
            "file-suffix": "jpg",
        },
        data=f,
    )
r.raise_for_status()
resource_id = r.json()["id"]

A resposta contém o identificador do ficheiro (id) e o respetivo tipo (type); estes dois valores serão utilizados no visual da campanha.

{
  "id": 1724832015443,
  "type": 2,
  "name": "promocao-verao",
  "width": 1920,
  "height": 1080,
  "duration": 0,
  "aspectRatio": 32
}

• Tamanho: ficheiros normais até cerca de 1,1 GB e vídeos com transparência até cerca de 2,1 GB. O servidor rejeita ficheiros maiores com 413.
• Preparação do vídeo: o vídeo é convertido em segundo plano após o carregamento. Está pronto quando os detalhes do ficheiro (GET /api/resource/single/{companyId}/{id}) contêm um valor em dt_ready. As imagens ficam prontas praticamente de imediato.
• Cabeçalho em falta: sem file-mime, file-name ou file-suffix o servidor devolve 204 e não cria o ficheiro multimédia. Verifique sempre se a resposta contém id antes de continuar.

3. Modelo de campanha

Não construa a campanha manualmente. Peça um modelo que o servidor preenche com um período predefinido de um mês a partir de hoje, as definições da empresa e todos os locais e dispositivos. Cada dispositivo surge marcado como isActive: false.

curl -u "$AUTH" "$API/api/campaign/company/$COMPANY" > campaign.json

Exemplo de modelo abreviado:

{
  "id": -1,
  "groupId": -1,
  "state": 2,
  "name": "",
  "start": "2026-11-01T10:00:00",
  "end": "2026-12-01T10:00:00",
  "isCommercial": true,
  "isNonCommercial": false,
  "settings": {
    "type": 2,
    "companyCount": 10,
    "companyDuration": 10000,
    "campaignCount": 1,
    "campaignDuration": 10000
  },
  "locations": [
    {
      "id": 1698234512100,
      "name": "Centro comercial do centro",
      "days": [ { "day": 1, "start": "09:00", "end": "21:00" } ],
      "devices": [
        {
          "id": 1698234512201,
          "name": "Entrada A",
          "screenRatio": 32,
          "isHorizontal": true,
          "isActive": false
        }
      ]
    }
  ],
  "visuals": []
}

O valor de settings.type determina o modo de reprodução da empresa: 2 = SLOT, 4 = IMPRESSION. O fornecedor define o modo, que não pode ser alterado através da API.

4. Edição do modelo

• name: nome da campanha apresentado na administração e nos relatórios.
• start, end: início e fim da campanha.
• isActive: definir como true para os dispositivos em que a campanha deve ser reproduzida.
• visuals: adicionar um visual com o ficheiro carregado.

"visuals": [
  {
    "id": 1,
    "name": "Visual principal",
    "isPrimary": true,
    "isCustom": true,
    "res": [
      {
        "id": 1,
        "conditionId": 0,
        "resourceId": 1724832015443,
        "name": "promocao-verao",
        "duration": 10000,
        "type": 2
      }
    ]
  }
]

O modelo pode ser editado por um script, por exemplo, com jq:

jq --argjson res "$RESOURCE" '
  .name = "Promoção de verão 2026"
  | .start = "2026-11-02T00:00:00"
  | .end   = "2026-11-09T00:00:00"
  | .locations[].devices[].isActive = true
  | .visuals = [{
      id: 1, name: "Visual principal", isPrimary: true, isCustom: true,
      res: [{ id: 1, conditionId: 0, resourceId: $res,
              name: "promocao-verao", duration: 10000, type: 2 }]
    }]
' campaign.json > campaign-edited.json

Se a campanha se destinar a ecrãs horizontais e verticais (isHorizontal), adicione um visual para cada orientação. Caso contrário, o conteúdo será cortado ou reduzido em alguns ecrãs. Consulte Visuais das campanhas para obter mais informações.

5. Criação da campanha

curl -u "$AUTH" -X POST \
  "$API/api/campaign/company/$COMPANY" \
  -H "Content-Type: application/json" \
  --data @campaign-edited.json \
  -o response.json

export CAMPAIGN=$(jq -r '.id' response.json)
export GROUP=$(jq -r '.groupId' response.json)

A campanha é criada como rascunho e não é reproduzida em nenhum dispositivo. A resposta contém a campanha guardada com os valores atribuídos de id e groupId. O modelo já contém state: 2 (rascunho); o servidor rejeita qualquer outro valor com 409.

6. Ativação da campanha

curl -u "$AUTH" -X PATCH \
  "$API/api/campaign/company/$COMPANY/$CAMPAIGN/+01:00/0"

• +01:00: fuso horário da campanha como desvio em relação a UTC. Para a Europa Central, utilize +01:00 no inverno e +02:00 durante a hora de verão.
• 0: número de impressões esperado para toda a campanha. Aplica-se no modo IMPRESSION; no modo SLOT, utilize 0.

Uma campanha com início hoje ou anterior passa a ativa e o início é definido para o momento da ativação. Uma campanha com início futuro passa a publicada e começa no dia previsto.

O sistema recalcula o plano de reprodução e envia-o para os dispositivos afetados. Nos dispositivos ligados, isto demora normalmente algumas dezenas de segundos; um dispositivo desligado recebe o plano quando a ligação é restabelecida. Verifique a capacidade na administração; consulte Capacidade das campanhas.

7. Resultados da campanha

curl -u "$AUTH" "$API/api/report/$COMPANY/campaign/$GROUP"
curl -u "$AUTH" "$API/api/report/$COMPANY/campaign/$GROUP/impression"

Os relatórios utilizam groupId, e não o identificador da campanha id. O primeiro endpoint devolve o resumo da campanha; o segundo, os números de impressões registadas. Os dispositivos enviam registos continuamente em lotes, pelo que os valores não estão disponíveis em tempo real. Consulte Relatório da campanha para conhecer o significado dos valores.

Pausar, parar e eliminar

# Pausar uma campanha ativa; uma nova chamada retoma-a
curl -u "$AUTH" -X PATCH \
  "$API/api/campaign/company/$COMPANY/$CAMPAIGN/+01:00/0"

# Parar definitivamente
curl -u "$AUTH" -X PATCH \
  "$API/api/campaign/company/$COMPANY/$CAMPAIGN/+01:00"

# Eliminar
curl -u "$AUTH" -X DELETE \
  "$API/api/campaign/company/$COMPANY/$CAMPAIGN"

O endpoint do passo 6 funciona como um comutador: pausa uma campanha ativa ou publicada e retoma uma campanha pausada. Verifique o estado atual (state nos detalhes) antes da chamada. Uma campanha parada não pode voltar a ser iniciada, mas permanece na lista com os respetivos relatórios. Uma campanha eliminada desaparece da lista.

Resumo dos endpoints

Os percursos são relativos ao endereço da administração. {c} representa o identificador da empresa.

Conta

Multimédia

Campanhas

Locais e dispositivos

Relatórios

Listas de valores

Os valores das listas são escritos como números em JSON.

Estado da campanha (state)

Tipos de multimédia

Para os documentos, o cabeçalho file-type utiliza o valor PDF, não DOCUMENT.

Permissões

A interface aplica as mesmas permissões que a administração e verifica-as em cada pedido. Na resposta de início de sessão, cada área é expressa por um número igual à soma dos direitos individuais:

Por exemplo, resource: 28 (4 + 8 + 16) significa que o utilizador pode ver, adicionar e editar conteúdos multimédia, mas não eliminá-los. Os valores superiores (128 como 1024) representam os mesmos direitos fora da empresa do utilizador; uma integração não necessita deles.

Ativar, pausar e parar uma campanha exige o direito Adicionar. Eliminar uma campanha ativada ou um ficheiro exige o direito Eliminar; um rascunho pode ser eliminado sem esse direito. Um bom ponto de partida é a função Gestor de publicidade da empresa, removendo os direitos desnecessários.

Códigos de erro

Exemplo completo

O script executa todo o processo, desde o carregamento de uma imagem até à ativação de uma campanha em todos os dispositivos da empresa. Requer curl e jq.

#!/usr/bin/env bash
set -euo pipefail

API="https://admin.example.org"
AUTH="${INTEGRATION_AUTH:?defina INTEGRATION_AUTH=utilizador:palavra-passe}"
FILE="promocao-verao.jpg"
NAME="Promoção de verão 2026"
FROM="2026-11-02T00:00:00"
TO="2026-11-09T00:00:00"
TZ_OFFSET="+01:00"

# 1) Identificador da empresa
COMPANY=$(curl -sf -u "$AUTH" "$API/api/public/login" | jq -r '.company.id')

# 2) Carregar o ficheiro multimédia
RESOURCE=$(curl -sf -u "$AUTH" -X PUT \
  "$API/api/resource/single/$COMPANY" \
  -H "file-type: IMAGE" \
  -H "file-mime: image/jpeg" \
  -H "file-name: $FILE" \
  -H "file-suffix: jpg" \
  --data-binary "@$FILE" | jq -r '.id')

# 3) Modelo de campanha
curl -sf -u "$AUTH" "$API/api/campaign/company/$COMPANY" > template.json

# 4) Editar o modelo
jq --argjson res "$RESOURCE" --arg n "$NAME" --arg from "$FROM" --arg to "$TO" '
  .name = $n
  | .start = $from
  | .end = $to
  | .locations[].devices[].isActive = true
  | .visuals = [{
      id: 1, name: "Visual principal", isPrimary: true, isCustom: true,
      res: [{ id: 1, conditionId: 0, resourceId: $res,
              name: $n, duration: 10000, type: 2 }]
    }]
' template.json > campaign.json

# 5) Criar um rascunho
RESPONSE=$(curl -sf -u "$AUTH" -X POST \
  "$API/api/campaign/company/$COMPANY" \
  -H "Content-Type: application/json" \
  --data @campaign.json)
CAMPAIGN=$(echo "$RESPONSE" | jq -r '.id')
GROUP=$(echo "$RESPONSE" | jq -r '.groupId')

# 6) Ativar
curl -sf -u "$AUTH" -X PATCH \
  "$API/api/campaign/company/$COMPANY/$CAMPAIGN/$TZ_OFFSET/0" > /dev/null

echo "Campanha $CAMPAIGN ativada, relatório: $API/api/report/$COMPANY/campaign/$GROUP"