Endpoints públicos e SDK v1

SDK · v1 · Produção · Revisado em 2026-10-19 · Markdown

Estas interfaces existentes usam bases diferentes da API administrativa. Use os hosts exatos autorizados da sua instalação. Não envie chaves administrativas. Os hosts e tokens abaixo são fictícios. Leia o ciclo e os limites e consulte o OpenAPI público. Detecção exige opt-in e recuperação tem capacidade transitória; exemplos não criam desafios ou recibos válidos.

GET /v1/links/{id}

Resolver metadados públicos. Contrato público existente, separado de administração. Detecção exige opt-in; não chamar sua rota Edge interna diretamente. Capacidades e validade são revalidadas no servidor.

Base de exemplo: https://edge.agilink.invalid/functions/v1/api.

Parâmetro	Local	Obrigatório
`id`	path	sim
`appId`	query	sim

Sem corpo de requisição. Associações também aceitam HEAD com corpo de resposta vazio.

curl --request GET 'https://edge.agilink.invalid/functions/v1/api/v1/links/go.example.com~-a~-produto?appId=app_loja'

Resposta 200: Sucesso; exemplos fictícios. ACKs de telemetria devem ser lidos por evento.

{
  "version": 1,
  "link": {
    "id": "go.example.com~-a~-produto",
    "appId": "app_loja",
    "domain": "go.example.com",
    "prefix": "a",
    "slug": "produto",
    "appPath": "produto/123",
    "title": "Produto",
    "description": null,
    "imageUrl": null,
    "webUrl": "https://shop.example.com/produto/123",
    "webOnly": false,
    "parameters": {
      "sku": "123"
    }
  }
}

Erros documentados: 400, 403, 404, 503. Erros do Worker podem ter corpo vazio. Etapas de recuperação podem responder 200 {"accepted":false}; ACK HTTP não significa conteúdo exibido. Consulte os schemas e o guia para condições, validade, retry e envelopes.

Página própria desta operação.

POST /v1/events

Enviar lote de telemetria client_reported. Contrato público existente, separado de administração. Detecção exige opt-in; não chamar sua rota Edge interna diretamente. Capacidades e validade são revalidadas no servidor.

Base de exemplo: https://edge.agilink.invalid/functions/v1/api.

Campo	Tipo	Obrigatório
`version`	constante	sim
`appId`	string	sim
`events`	array	sim

{
  "version": 1,
  "appId": "app_loja",
  "events": [
    {
      "eventId": "80000000-0000-4000-8000-000000000001",
      "openId": "80000000-0000-4000-8000-000000000002",
      "type": "app_open",
      "linkId": "go.example.com~-a~-produto",
      "occurredAt": "2026-10-19T12:00:00Z",
      "platform": "ios",
      "entryMethod": "https"
    }
  ]
}

curl --request POST 'https://edge.agilink.invalid/functions/v1/api/v1/events' \
  --header 'Content-Type: application/json' \
  --data '{"version":1,"appId":"app_loja","events":[{"eventId":"80000000-0000-4000-8000-000000000001","openId":"80000000-0000-4000-8000-000000000002","type":"app_open","linkId":"go.example.com~-a~-produto","occurredAt":"2026-10-19T12:00:00Z","platform":"ios","entryMethod":"https"}]}'

Resposta 200: Sucesso; exemplos fictícios. ACKs de telemetria devem ser lidos por evento.

{
  "version": 1,
  "results": [
    {
      "eventId": "80000000-0000-4000-8000-000000000001",
      "status": "accepted"
    }
  ]
}

Erros documentados: 400, 403, 413, 503. Erros do Worker podem ter corpo vazio. Etapas de recuperação podem responder 200 {"accepted":false}; ACK HTTP não significa conteúdo exibido. Consulte os schemas e o guia para condições, validade, retry e envelopes.

Página própria desta operação.

POST /v1/recovery/preview

Consultar recuperação sem consumir claim. Contrato público existente, separado de administração. Detecção exige opt-in; não chamar sua rota Edge interna diretamente. Capacidades e validade são revalidadas no servidor.

Base de exemplo: https://edge.agilink.invalid/functions/v1/api.

Campo	Tipo	Obrigatório
`version`	constante	sim
`appId`	string	sim
`token`	string	sim

{
  "version": 1,
  "appId": "app_loja",
  "token": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
}

curl --request POST 'https://edge.agilink.invalid/functions/v1/api/v1/recovery/preview' \
  --header 'Content-Type: application/json' \
  --data '{"version":1,"appId":"app_loja","token":"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"}'

Resposta 200: Sucesso; exemplos fictícios. ACKs de telemetria devem ser lidos por evento.

{
  "version": 1,
  "appId": "app_loja",
  "linkId": "go.example.com~-a~-produto",
  "context": {
    "publicUri": "https://go.example.com/a/produto"
  },
  "expiresAt": "2026-10-26T12:00:00Z"
}

Erros documentados: 400, 403, 404, 409, 410, 413, 429, 503. Erros do Worker podem ter corpo vazio. Etapas de recuperação podem responder 200 {"accepted":false}; ACK HTTP não significa conteúdo exibido. Consulte os schemas e o guia para condições, validade, retry e envelopes.

Página própria desta operação.

POST /v1/recovery/redeem

Reivindicar recuperação com claim persistido. Contrato público existente, separado de administração. Detecção exige opt-in; não chamar sua rota Edge interna diretamente. Capacidades e validade são revalidadas no servidor.

Base de exemplo: https://edge.agilink.invalid/functions/v1/api.

Campo	Tipo	Obrigatório
`version`	constante	sim
`appId`	string	sim
`token`	string	sim
`claimId`	string	sim

{
  "version": 1,
  "appId": "app_loja",
  "token": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
  "claimId": "80000000-0000-4000-8000-000000000002"
}

curl --request POST 'https://edge.agilink.invalid/functions/v1/api/v1/recovery/redeem' \
  --header 'Content-Type: application/json' \
  --data '{"version":1,"appId":"app_loja","token":"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA","claimId":"80000000-0000-4000-8000-000000000002"}'

Resposta 200: Sucesso; exemplos fictícios. ACKs de telemetria devem ser lidos por evento.

{
  "version": 1,
  "appId": "app_loja",
  "linkId": "go.example.com~-a~-produto",
  "context": {
    "publicUri": "https://go.example.com/a/produto"
  },
  "expiresAt": "2026-10-26T12:00:00Z"
}

Página própria desta operação.

POST /v1/recovery/stage

Registrar etapa declarada da recuperação. Contrato público existente, separado de administração. Detecção exige opt-in; não chamar sua rota Edge interna diretamente. Capacidades e validade são revalidadas no servidor.

Base de exemplo: https://edge.agilink.invalid/functions/v1/api.

Campo	Tipo	Obrigatório
`version`	constante	sim
`appId`	string	sim
`token`	string	sim
`eventId`	string	sim
`stage`	enum	sim

{
  "version": 1,
  "appId": "app_loja",
  "token": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
  "eventId": "80000000-0000-4000-8000-000000000001",
  "stage": "copied"
}

curl --request POST 'https://edge.agilink.invalid/functions/v1/api/v1/recovery/stage' \
  --header 'Content-Type: application/json' \
  --data '{"version":1,"appId":"app_loja","token":"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA","eventId":"80000000-0000-4000-8000-000000000001","stage":"copied"}'

Resposta 200: Sucesso; exemplos fictícios. ACKs de telemetria devem ser lidos por evento.

{
  "accepted": true
}

Página própria desta operação.

POST /_agilink/recovery/detection/challenge

Detecção opcional: challenge. Contrato público existente, separado de administração. Detecção exige opt-in; não chamar sua rota Edge interna diretamente. Capacidades e validade são revalidadas no servidor.

Base de exemplo: https://go.agilink.invalid.

Campo	Tipo	Obrigatório
`appId`	string	sim
`kind`	enum	sim
`linkId`	string	não

{
  "appId": "app_loja",
  "kind": "attempt"
}

curl --request POST 'https://go.agilink.invalid/_agilink/recovery/detection/challenge' \
  --header 'Content-Type: application/json' \
  --data '{"appId":"app_loja","kind":"attempt"}'

Resposta 200: Sucesso; exemplos fictícios. ACKs de telemetria devem ser lidos por evento.

{
  "version": 1,
  "nonce": "80000000-0000-4000-8000-000000000002",
  "challenge": "<challenge-assinado>",
  "expiresAt": "2026-10-19T12:02:00Z"
}

Erros documentados: 400, 403, 404, 405, 409, 410, 413, 415, 429, 502, 503. Erros do Worker podem ter corpo vazio. Etapas de recuperação podem responder 200 {"accepted":false}; ACK HTTP não significa conteúdo exibido. Consulte os schemas e o guia para condições, validade, retry e envelopes.

Página própria desta operação.

POST /_agilink/recovery/detection/click

Detecção opcional: click. Contrato público existente, separado de administração. Detecção exige opt-in; não chamar sua rota Edge interna diretamente. Capacidades e validade são revalidadas no servidor.

Base de exemplo: https://go.agilink.invalid.

Campo	Tipo	Obrigatório
`appId`	string	sim
`challenge`	string	sim
`signals`	DetectionSignals	sim

{
  "appId": "app_loja",
  "challenge": "<challenge-assinado>",
  "signals": {
    "platform": "ios",
    "family": "iphone",
    "osVersion": "18.0",
    "language": "pt-BR",
    "timezone": "America/Sao_Paulo",
    "screen": {
      "width": 390,
      "height": 844,
      "scale": 3
    }
  }
}

curl --request POST 'https://go.agilink.invalid/_agilink/recovery/detection/click' \
  --header 'Content-Type: application/json' \
  --data '{"appId":"app_loja","challenge":"<challenge-assinado>","signals":{"platform":"ios","family":"iphone","osVersion":"18.0","language":"pt-BR","timezone":"America/Sao_Paulo","screen":{"width":390,"height":844,"scale":3}}}'

Resposta 200: Sucesso; exemplos fictícios. ACKs de telemetria devem ser lidos por evento.

{
  "version": 1,
  "mode": "detection",
  "accepted": true,
  "intentReceipt": "<recibo-de-intencao>"
}

Página própria desta operação.

POST /_agilink/recovery/detection/intent

Detecção opcional: intent. Contrato público existente, separado de administração. Detecção exige opt-in; não chamar sua rota Edge interna diretamente. Capacidades e validade são revalidadas no servidor.

Base de exemplo: https://go.agilink.invalid.

Campo	Tipo	Obrigatório
`appId`	string	sim
`intentReceipt`	string	sim

{
  "appId": "app_loja",
  "intentReceipt": "<recibo-de-intencao>"
}

curl --request POST 'https://go.agilink.invalid/_agilink/recovery/detection/intent' \
  --header 'Content-Type: application/json' \
  --data '{"appId":"app_loja","intentReceipt":"<recibo-de-intencao>"}'

Resposta 200: Sucesso; exemplos fictícios. ACKs de telemetria devem ser lidos por evento.

{
  "version": 1,
  "mode": "detection",
  "accepted": true
}

Página própria desta operação.

POST /_agilink/recovery/detection/attempt

Detecção opcional: attempt. Contrato público existente, separado de administração. Detecção exige opt-in; não chamar sua rota Edge interna diretamente. Capacidades e validade são revalidadas no servidor.

Base de exemplo: https://go.agilink.invalid.

Campo	Tipo	Obrigatório
`appId`	string	sim
`challenge`	string	sim
`attemptId`	string	sim
`signals`	DetectionSignals	sim

{
  "appId": "app_loja",
  "challenge": "<challenge-assinado>",
  "attemptId": "80000000-0000-4000-8000-000000000002",
  "signals": {
    "platform": "ios",
    "family": "iphone",
    "osVersion": "18.0",
    "language": "pt-BR",
    "timezone": "America/Sao_Paulo",
    "screen": {
      "width": 390,
      "height": 844,
      "scale": 3
    }
  }
}

curl --request POST 'https://go.agilink.invalid/_agilink/recovery/detection/attempt' \
  --header 'Content-Type: application/json' \
  --data '{"appId":"app_loja","challenge":"<challenge-assinado>","attemptId":"80000000-0000-4000-8000-000000000002","signals":{"platform":"ios","family":"iphone","osVersion":"18.0","language":"pt-BR","timezone":"America/Sao_Paulo","screen":{"width":390,"height":844,"scale":3}}}'

Resposta 200: Sucesso; exemplos fictícios. ACKs de telemetria devem ser lidos por evento.

{
  "version": 1,
  "mode": "detection",
  "status": "no_match",
  "reason": "no_candidate",
  "policyVersion": "agilink-shadow-v4-context"
}

Página própria desta operação.

POST /_agilink/recovery/detection/claim

Detecção opcional: claim. Contrato público existente, separado de administração. Detecção exige opt-in; não chamar sua rota Edge interna diretamente. Capacidades e validade são revalidadas no servidor.

Base de exemplo: https://go.agilink.invalid.

Campo	Tipo	Obrigatório
`appId`	string	sim
`receipt`	string	sim
`confirmed`	boolean	sim

{
  "appId": "app_loja",
  "receipt": "<recibo-do-candidato>",
  "confirmed": true
}

curl --request POST 'https://go.agilink.invalid/_agilink/recovery/detection/claim' \
  --header 'Content-Type: application/json' \
  --data '{"appId":"app_loja","receipt":"<recibo-do-candidato>","confirmed":true}'

Resposta 200: Sucesso; exemplos fictícios. ACKs de telemetria devem ser lidos por evento.

{
  "version": 1,
  "mode": "detection",
  "policyVersion": "agilink-shadow-v4-context",
  "publicUri": "https://go.example.com/a/produto",
  "linkId": "go.example.com~-a~-produto",
  "attemptId": "80000000-0000-4000-8000-000000000002"
}

Página própria desta operação.

GET /.well-known/assetlinks.json

Consultar associação Android. Contrato público existente, separado de administração. Detecção exige opt-in; não chamar sua rota Edge interna diretamente. Capacidades e validade são revalidadas no servidor.

Base de exemplo: https://go.agilink.invalid.

Sem corpo de requisição. Associações também aceitam HEAD com corpo de resposta vazio.

curl --request GET 'https://go.agilink.invalid/.well-known/assetlinks.json'

Resposta 200: Sucesso; exemplos fictícios. ACKs de telemetria devem ser lidos por evento.

[]

Erros documentados: 404, 405, 503. Erros do Worker podem ter corpo vazio. Etapas de recuperação podem responder 200 {"accepted":false}; ACK HTTP não significa conteúdo exibido. Consulte os schemas e o guia para condições, validade, retry e envelopes.

Página própria desta operação.

GET /.well-known/apple-app-site-association

Consultar associação iOS. Contrato público existente, separado de administração. Detecção exige opt-in; não chamar sua rota Edge interna diretamente. Capacidades e validade são revalidadas no servidor.

Base de exemplo: https://go.agilink.invalid.

Sem corpo de requisição. Associações também aceitam HEAD com corpo de resposta vazio.

curl --request GET 'https://go.agilink.invalid/.well-known/apple-app-site-association'

Resposta 200: Sucesso; exemplos fictícios. ACKs de telemetria devem ser lidos por evento.

{
  "applinks": {
    "apps": [],
    "details": []
  }
}

Página própria desta operação.

GET /apple-app-site-association

Consultar alias AASA. Contrato público existente, separado de administração. Detecção exige opt-in; não chamar sua rota Edge interna diretamente. Capacidades e validade são revalidadas no servidor.

Base de exemplo: https://go.agilink.invalid.

Sem corpo de requisição. Associações também aceitam HEAD com corpo de resposta vazio.

curl --request GET 'https://go.agilink.invalid/apple-app-site-association'

Resposta 200: Sucesso; exemplos fictícios. ACKs de telemetria devem ser lidos por evento.

{
  "applinks": {
    "apps": [],
    "details": []
  }
}

Página própria desta operação.