Criar um link

Disponível em homologação

Endpoint disponível em https://api.staging.agilink.io/v1. Os exemplos abaixo são gerados dos mesmos dados validados pelo contrato e usam um host fictício.

Cria um link em aplicativo e domínio autorizados. A credencial precisa de links:create e acesso ao aplicativo. A publicação no redirecionador pode continuar pendente após o cadastro.

Requisição

POST /v1/links, com Authorization: Bearer <sua-chave>, Content-Type: application/json e Idempotency-Key: 10000000-0000-4000-8000-000000000001.

{
  "appId": "app_loja",
  "domain": "go.example.com",
  "prefix": "ofertas",
  "slug": "tenis",
  "title": "Tênis da campanha",
  "desktopUrl": "https://shop.example.com/produtos/tenis",
  "appPath": "produtos/tenis"
}

appPath é relativo, sem barra inicial. Use o caminho que seu aplicativo reconhece. O domínio e o aplicativo deste exemplo são fictícios.

cURL

curl --request POST 'https://api.staging.agilink.io/v1/links' \
  --header 'Authorization: Bearer <sua-chave>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: 10000000-0000-4000-8000-000000000001' \
  --data '{"appId":"app_loja","domain":"go.example.com","prefix":"ofertas","slug":"tenis","title":"Tênis da campanha","desktopUrl":"https://shop.example.com/produtos/tenis","appPath":"produtos/tenis"}'

Resposta

201 Created, com Location: /v1/links/go.example.com~-ofertas~-tenis e ETag: "20000000-0000-4000-8000-000000000001".

{
  "data": {
    "id": "go.example.com~-ofertas~-tenis",
    "appId": "app_loja",
    "domain": "go.example.com",
    "prefix": "ofertas",
    "slug": "tenis",
    "url": "https://go.example.com/ofertas/tenis",
    "title": "Tênis da campanha",
    "description": null,
    "imageUrl": null,
    "desktopUrl": "https://shop.example.com/produtos/tenis",
    "appPath": "produtos/tenis",
    "parameters": {},
    "webOnly": false,
    "behavior": "manual",
    "group": "operational",
    "origin": "api",
    "revision": "20000000-0000-4000-8000-000000000001",
    "createdAt": "2026-10-19T20:00:00Z",
    "updatedAt": "2026-10-19T20:00:00Z",
    "publication": {
      "status": "pending",
      "desiredRevision": "20000000-0000-4000-8000-000000000001",
      "confirmedRevision": null,
      "updatedAt": "2026-10-19T20:00:00Z"
    }
  },
  "meta": {
    "requestId": "req_00000000000040008000000000000001"
  }
}

Consulte o link e sua publicação para acompanhar a revisão. Não confunda 201 com sincronização já confirmada em todos os pontos.

Erros e repetição

Status	Quando ocorre	Próxima ação
401	Chave inválida, expirada ou revogada	Verificar credencial
403	Falta de permissão	Solicitar permissão ao dono
404	Aplicativo/recurso fora do acesso autorizado	Conferir app e domínio
409	Slug ocupado, idempotência conflitante ou em andamento	Consultar o resultado; preservar a intenção
422	Dados de domínio inválidos	Corrigir os campos indicados
429	Limite excedido	Aguardar Retry-After

Em timeout ou resultado incerto, repita a mesma intenção com a mesma chave de idempotência e o mesmo corpo dentro da janela de 24 horas. Para alterar um link, consulte a revisão e use If-Match; uma revisão antiga retorna:

{
  "error": {
    "code": "revision_conflict",
    "message": "O link foi alterado. Consulte a revisão atual.",
    "details": [
      {
        "field": "If-Match",
        "reason": "stale"
      }
    ],
    "requestId": "req_00000000000040008000000000000001",
    "documentationUrl": "https://docs.agilink.io/api/errors/#revision-conflict"
  }
}

Veja os campos do produto, as convenções e a referência completa da prévia.