{ "openapi": "3.1.1", "info": { "title": "Agilink — contratos públicos e SDK v1", "version": "1.0.0", "description": "Formatos existentes. Não confundir com a Platform API administrativa. Hosts fictícios; o guia informa como escolher bases fixas.", "contact": { "name": "Agilink", "url": "https://agilink.io" } }, "servers": [ { "url": "https://edge.agilink.invalid/functions/v1/api", "description": "Base fixa da API pública da instalação; não é /platform/v1" } ], "security": [], "tags": [ { "name": "resolution", "description": "Contratos públicos: resolution" }, { "name": "telemetry", "description": "Contratos públicos: telemetry" }, { "name": "recovery", "description": "Contratos públicos: recovery" }, { "name": "detection", "description": "Contratos públicos: detection" }, { "name": "association", "description": "Contratos públicos: association" } ], "paths": { "/v1/links/{id}": { "get": { "operationId": "get_v1_links__id_", "summary": "Resolver metadados públicos", "description": "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.", "tags": [ "resolution" ], "servers": [ { "url": "https://edge.agilink.invalid/functions/v1/api", "description": "Base fixa da API pública da instalação; não é /platform/v1" } ], "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 500 } }, { "name": "appId", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Sucesso; exemplos fictícios. ACKs de telemetria devem ser lidos por evento.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "Associação GET/HEAD: max-age=300; falha de configuração não recebe cache de sucesso." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/resolution.schema" }, "example": { "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" } } } } } }, "400": { "description": "Erro público existente; código e estado conforme o guia.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "code": "invalid_argument" } } } }, "403": { "description": "Erro público existente; código e estado conforme o guia.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "code": "invalid_argument" } } } }, "404": { "description": "Erro público existente; código e estado conforme o guia.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "code": "not_found" } } } }, "503": { "description": "Erro público existente; código e estado conforme o guia.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "code": "invalid_argument" } } } } } } }, "/v1/events": { "post": { "operationId": "post_v1_events", "summary": "Enviar lote de telemetria client_reported", "description": "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.", "tags": [ "telemetry" ], "servers": [ { "url": "https://edge.agilink.invalid/functions/v1/api", "description": "Base fixa da API pública da instalação; não é /platform/v1" } ], "security": [], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NativeBatch" }, "example": { "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" } ] } } } }, "responses": { "200": { "description": "Sucesso; exemplos fictícios. ACKs de telemetria devem ser lidos por evento.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "Associação GET/HEAD: max-age=300; falha de configuração não recebe cache de sucesso." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NativeAck" }, "example": { "version": 1, "results": [ { "eventId": "80000000-0000-4000-8000-000000000001", "status": "accepted" } ] } } } }, "400": { "description": "Erro público existente; código e estado conforme o guia.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "code": "invalid_argument" } } } }, "403": { "description": "Erro público existente; código e estado conforme o guia.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "code": "invalid_argument" } } } }, "413": { "description": "Erro público existente; código e estado conforme o guia.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "code": "invalid_argument" } } } }, "503": { "description": "Erro público existente; código e estado conforme o guia.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "code": "invalid_argument" } } } } } } }, "/v1/recovery/preview": { "post": { "operationId": "post_v1_recovery_preview", "summary": "Consultar recuperação sem consumir claim", "description": "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.", "tags": [ "recovery" ], "servers": [ { "url": "https://edge.agilink.invalid/functions/v1/api", "description": "Base fixa da API pública da instalação; não é /platform/v1" } ], "security": [], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecoveryRead" }, "example": { "version": 1, "appId": "app_loja", "token": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" } } } }, "responses": { "200": { "description": "Sucesso; exemplos fictícios. ACKs de telemetria devem ser lidos por evento.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "Associação GET/HEAD: max-age=300; falha de configuração não recebe cache de sucesso." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecoveryResult" }, "example": { "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" } } } }, "400": { "description": "Erro público existente; código e estado conforme o guia.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "code": "invalid_argument" } } } }, "403": { "description": "Erro público existente; código e estado conforme o guia.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "code": "invalid_argument" } } } }, "404": { "description": "Erro público existente; código e estado conforme o guia.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "code": "not_found" } } } }, "409": { "description": "Erro público existente; código e estado conforme o guia.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "code": "invalid_argument" } } } }, "410": { "description": "Erro público existente; código e estado conforme o guia.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "code": "expired" } } } }, "413": { "description": "Erro público existente; código e estado conforme o guia.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "code": "invalid_argument" } } } }, "429": { "description": "Erro público existente; código e estado conforme o guia.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "code": "rate_limited" } } } }, "503": { "description": "Erro público existente; código e estado conforme o guia.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "code": "invalid_argument" } } } } } } }, "/v1/recovery/redeem": { "post": { "operationId": "post_v1_recovery_redeem", "summary": "Reivindicar recuperação com claim persistido", "description": "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.", "tags": [ "recovery" ], "servers": [ { "url": "https://edge.agilink.invalid/functions/v1/api", "description": "Base fixa da API pública da instalação; não é /platform/v1" } ], "security": [], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecoveryRedeem" }, "example": { "version": 1, "appId": "app_loja", "token": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "claimId": "80000000-0000-4000-8000-000000000002" } } } }, "responses": { "200": { "description": "Sucesso; exemplos fictícios. ACKs de telemetria devem ser lidos por evento.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "Associação GET/HEAD: max-age=300; falha de configuração não recebe cache de sucesso." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecoveryResult" }, "example": { "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" } } } }, "400": { "description": "Erro público existente; código e estado conforme o guia.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "code": "invalid_argument" } } } }, "403": { "description": "Erro público existente; código e estado conforme o guia.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "code": "invalid_argument" } } } }, "404": { "description": "Erro público existente; código e estado conforme o guia.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "code": "not_found" } } } }, "409": { "description": "Erro público existente; código e estado conforme o guia.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "code": "invalid_argument" } } } }, "410": { "description": "Erro público existente; código e estado conforme o guia.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "code": "expired" } } } }, "413": { "description": "Erro público existente; código e estado conforme o guia.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "code": "invalid_argument" } } } }, "429": { "description": "Erro público existente; código e estado conforme o guia.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "code": "rate_limited" } } } }, "503": { "description": "Erro público existente; código e estado conforme o guia.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "code": "invalid_argument" } } } } } } }, "/v1/recovery/stage": { "post": { "operationId": "post_v1_recovery_stage", "summary": "Registrar etapa declarada da recuperação", "description": "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.", "tags": [ "recovery" ], "servers": [ { "url": "https://edge.agilink.invalid/functions/v1/api", "description": "Base fixa da API pública da instalação; não é /platform/v1" } ], "security": [], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecoveryStage" }, "example": { "version": 1, "appId": "app_loja", "token": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "eventId": "80000000-0000-4000-8000-000000000001", "stage": "copied" } } } }, "responses": { "200": { "description": "Sucesso; exemplos fictícios. ACKs de telemetria devem ser lidos por evento.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "Associação GET/HEAD: max-age=300; falha de configuração não recebe cache de sucesso." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecoveryStageAck" }, "example": { "accepted": true } } } }, "400": { "description": "Erro público existente; código e estado conforme o guia.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "code": "invalid_argument" } } } }, "403": { "description": "Erro público existente; código e estado conforme o guia.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "code": "invalid_argument" } } } }, "413": { "description": "Erro público existente; código e estado conforme o guia.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "code": "invalid_argument" } } } }, "503": { "description": "Erro público existente; código e estado conforme o guia.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "example": { "code": "invalid_argument" } } } } } } }, "/_agilink/recovery/detection/challenge": { "post": { "operationId": "post__agilink_recovery_detection_challenge", "summary": "Detecção opcional: challenge", "description": "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.", "tags": [ "detection" ], "servers": [ { "url": "https://go.agilink.invalid", "description": "Hostname público exato autorizado no SDK" } ], "security": [], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DetectionChallenge" }, "example": { "appId": "app_loja", "kind": "attempt" } } } }, "responses": { "200": { "description": "Sucesso; exemplos fictícios. ACKs de telemetria devem ser lidos por evento.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "Associação GET/HEAD: max-age=300; falha de configuração não recebe cache de sucesso." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DetectionChallengeResult" }, "example": { "version": 1, "nonce": "80000000-0000-4000-8000-000000000002", "challenge": "", "expiresAt": "2026-10-19T12:02:00Z" } } } }, "400": { "description": "Pode ter corpo vazio; não presumir envelope administrativo. Consulte o guia público." }, "403": { "description": "Pode ter corpo vazio; não presumir envelope administrativo. Consulte o guia público." }, "404": { "description": "Pode ter corpo vazio; não presumir envelope administrativo. Consulte o guia público." }, "405": { "description": "Pode ter corpo vazio; não presumir envelope administrativo. Consulte o guia público." }, "409": { "description": "Pode ter corpo vazio; não presumir envelope administrativo. Consulte o guia público." }, "410": { "description": "Pode ter corpo vazio; não presumir envelope administrativo. Consulte o guia público." }, "413": { "description": "Pode ter corpo vazio; não presumir envelope administrativo. Consulte o guia público." }, "415": { "description": "Pode ter corpo vazio; não presumir envelope administrativo. Consulte o guia público." }, "429": { "description": "Pode ter corpo vazio; não presumir envelope administrativo. Consulte o guia público." }, "502": { "description": "Pode ter corpo vazio; não presumir envelope administrativo. Consulte o guia público." }, "503": { "description": "Pode ter corpo vazio; não presumir envelope administrativo. Consulte o guia público." } } } }, "/_agilink/recovery/detection/click": { "post": { "operationId": "post__agilink_recovery_detection_click", "summary": "Detecção opcional: click", "description": "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.", "tags": [ "detection" ], "servers": [ { "url": "https://go.agilink.invalid", "description": "Hostname público exato autorizado no SDK" } ], "security": [], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DetectionClick" }, "example": { "appId": "app_loja", "challenge": "", "signals": { "platform": "ios", "family": "iphone", "osVersion": "18.0", "language": "pt-BR", "timezone": "America/Sao_Paulo", "screen": { "width": 390, "height": 844, "scale": 3 } } } } } }, "responses": { "200": { "description": "Sucesso; exemplos fictícios. ACKs de telemetria devem ser lidos por evento.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "Associação GET/HEAD: max-age=300; falha de configuração não recebe cache de sucesso." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DetectionCaptureAck" }, "example": { "version": 1, "mode": "detection", "accepted": true, "intentReceipt": "" } } } }, "400": { "description": "Pode ter corpo vazio; não presumir envelope administrativo. Consulte o guia público." }, "403": { "description": "Pode ter corpo vazio; não presumir envelope administrativo. Consulte o guia público." }, "404": { "description": "Pode ter corpo vazio; não presumir envelope administrativo. Consulte o guia público." }, "405": { "description": "Pode ter corpo vazio; não presumir envelope administrativo. Consulte o guia público." }, "409": { "description": "Pode ter corpo vazio; não presumir envelope administrativo. Consulte o guia público." }, "410": { "description": "Pode ter corpo vazio; não presumir envelope administrativo. Consulte o guia público." }, "413": { "description": "Pode ter corpo vazio; não presumir envelope administrativo. Consulte o guia público." }, "415": { "description": "Pode ter corpo vazio; não presumir envelope administrativo. Consulte o guia público." }, "429": { "description": "Pode ter corpo vazio; não presumir envelope administrativo. Consulte o guia público." }, "502": { "description": "Pode ter corpo vazio; não presumir envelope administrativo. Consulte o guia público." }, "503": { "description": "Pode ter corpo vazio; não presumir envelope administrativo. Consulte o guia público." } } } }, "/_agilink/recovery/detection/intent": { "post": { "operationId": "post__agilink_recovery_detection_intent", "summary": "Detecção opcional: intent", "description": "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.", "tags": [ "detection" ], "servers": [ { "url": "https://go.agilink.invalid", "description": "Hostname público exato autorizado no SDK" } ], "security": [], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DetectionIntent" }, "example": { "appId": "app_loja", "intentReceipt": "" } } } }, "responses": { "200": { "description": "Sucesso; exemplos fictícios. ACKs de telemetria devem ser lidos por evento.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "Associação GET/HEAD: max-age=300; falha de configuração não recebe cache de sucesso." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DetectionCaptureAck" }, "example": { "version": 1, "mode": "detection", "accepted": true } } } }, "400": { "description": "Pode ter corpo vazio; não presumir envelope administrativo. Consulte o guia público." }, "403": { "description": "Pode ter corpo vazio; não presumir envelope administrativo. Consulte o guia público." }, "404": { "description": "Pode ter corpo vazio; não presumir envelope administrativo. Consulte o guia público." }, "405": { "description": "Pode ter corpo vazio; não presumir envelope administrativo. Consulte o guia público." }, "409": { "description": "Pode ter corpo vazio; não presumir envelope administrativo. Consulte o guia público." }, "410": { "description": "Pode ter corpo vazio; não presumir envelope administrativo. Consulte o guia público." }, "413": { "description": "Pode ter corpo vazio; não presumir envelope administrativo. Consulte o guia público." }, "415": { "description": "Pode ter corpo vazio; não presumir envelope administrativo. Consulte o guia público." }, "429": { "description": "Pode ter corpo vazio; não presumir envelope administrativo. Consulte o guia público." }, "502": { "description": "Pode ter corpo vazio; não presumir envelope administrativo. Consulte o guia público." }, "503": { "description": "Pode ter corpo vazio; não presumir envelope administrativo. Consulte o guia público." } } } }, "/_agilink/recovery/detection/attempt": { "post": { "operationId": "post__agilink_recovery_detection_attempt", "summary": "Detecção opcional: attempt", "description": "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.", "tags": [ "detection" ], "servers": [ { "url": "https://go.agilink.invalid", "description": "Hostname público exato autorizado no SDK" } ], "security": [], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DetectionAttempt" }, "example": { "appId": "app_loja", "challenge": "", "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 } } } } } }, "responses": { "200": { "description": "Sucesso; exemplos fictícios. ACKs de telemetria devem ser lidos por evento.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "Associação GET/HEAD: max-age=300; falha de configuração não recebe cache de sucesso." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DetectionResult" }, "example": { "version": 1, "mode": "detection", "status": "no_match", "reason": "no_candidate", "policyVersion": "agilink-shadow-v4-context" } } } }, "400": { "description": "Pode ter corpo vazio; não presumir envelope administrativo. Consulte o guia público." }, "403": { "description": "Pode ter corpo vazio; não presumir envelope administrativo. Consulte o guia público." }, "404": { "description": "Pode ter corpo vazio; não presumir envelope administrativo. Consulte o guia público." }, "405": { "description": "Pode ter corpo vazio; não presumir envelope administrativo. Consulte o guia público." }, "409": { "description": "Pode ter corpo vazio; não presumir envelope administrativo. Consulte o guia público." }, "410": { "description": "Pode ter corpo vazio; não presumir envelope administrativo. Consulte o guia público." }, "413": { "description": "Pode ter corpo vazio; não presumir envelope administrativo. Consulte o guia público." }, "415": { "description": "Pode ter corpo vazio; não presumir envelope administrativo. Consulte o guia público." }, "429": { "description": "Pode ter corpo vazio; não presumir envelope administrativo. Consulte o guia público." }, "502": { "description": "Pode ter corpo vazio; não presumir envelope administrativo. Consulte o guia público." }, "503": { "description": "Pode ter corpo vazio; não presumir envelope administrativo. Consulte o guia público." } } } }, "/_agilink/recovery/detection/claim": { "post": { "operationId": "post__agilink_recovery_detection_claim", "summary": "Detecção opcional: claim", "description": "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.", "tags": [ "detection" ], "servers": [ { "url": "https://go.agilink.invalid", "description": "Hostname público exato autorizado no SDK" } ], "security": [], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DetectionClaim" }, "example": { "appId": "app_loja", "receipt": "", "confirmed": true } } } }, "responses": { "200": { "description": "Sucesso; exemplos fictícios. ACKs de telemetria devem ser lidos por evento.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "Associação GET/HEAD: max-age=300; falha de configuração não recebe cache de sucesso." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DetectionClaimResult" }, "example": { "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" } } } }, "400": { "description": "Pode ter corpo vazio; não presumir envelope administrativo. Consulte o guia público." }, "403": { "description": "Pode ter corpo vazio; não presumir envelope administrativo. Consulte o guia público." }, "404": { "description": "Pode ter corpo vazio; não presumir envelope administrativo. Consulte o guia público." }, "405": { "description": "Pode ter corpo vazio; não presumir envelope administrativo. Consulte o guia público." }, "409": { "description": "Pode ter corpo vazio; não presumir envelope administrativo. Consulte o guia público." }, "410": { "description": "Pode ter corpo vazio; não presumir envelope administrativo. Consulte o guia público." }, "413": { "description": "Pode ter corpo vazio; não presumir envelope administrativo. Consulte o guia público." }, "415": { "description": "Pode ter corpo vazio; não presumir envelope administrativo. Consulte o guia público." }, "429": { "description": "Pode ter corpo vazio; não presumir envelope administrativo. Consulte o guia público." }, "502": { "description": "Pode ter corpo vazio; não presumir envelope administrativo. Consulte o guia público." }, "503": { "description": "Pode ter corpo vazio; não presumir envelope administrativo. Consulte o guia público." } } } }, "/.well-known/assetlinks.json": { "get": { "operationId": "get__well_known_assetlinks_json", "summary": "Consultar associação Android", "description": "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.", "tags": [ "association" ], "servers": [ { "url": "https://go.agilink.invalid", "description": "Hostname público exato autorizado no SDK" } ], "security": [], "parameters": [], "responses": { "200": { "description": "Sucesso; exemplos fictícios. ACKs de telemetria devem ser lidos por evento.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "Associação GET/HEAD: max-age=300; falha de configuração não recebe cache de sucesso." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetLinks" }, "example": [] } } }, "404": { "description": "Pode ter corpo vazio; não presumir envelope administrativo. Consulte o guia público." }, "405": { "description": "Pode ter corpo vazio; não presumir envelope administrativo. Consulte o guia público." }, "503": { "description": "Pode ter corpo vazio; não presumir envelope administrativo. Consulte o guia público." } } } }, "/.well-known/apple-app-site-association": { "get": { "operationId": "get__well_known_apple_app_site_association", "summary": "Consultar associação iOS", "description": "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.", "tags": [ "association" ], "servers": [ { "url": "https://go.agilink.invalid", "description": "Hostname público exato autorizado no SDK" } ], "security": [], "parameters": [], "responses": { "200": { "description": "Sucesso; exemplos fictícios. ACKs de telemetria devem ser lidos por evento.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "Associação GET/HEAD: max-age=300; falha de configuração não recebe cache de sucesso." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Aasa" }, "example": { "applinks": { "apps": [], "details": [] } } } } }, "404": { "description": "Pode ter corpo vazio; não presumir envelope administrativo. Consulte o guia público." }, "405": { "description": "Pode ter corpo vazio; não presumir envelope administrativo. Consulte o guia público." }, "503": { "description": "Pode ter corpo vazio; não presumir envelope administrativo. Consulte o guia público." } } } }, "/apple-app-site-association": { "get": { "operationId": "get_apple_app_site_association", "summary": "Consultar alias AASA", "description": "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.", "tags": [ "association" ], "servers": [ { "url": "https://go.agilink.invalid", "description": "Hostname público exato autorizado no SDK" } ], "security": [], "parameters": [], "responses": { "200": { "description": "Sucesso; exemplos fictícios. ACKs de telemetria devem ser lidos por evento.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "Associação GET/HEAD: max-age=300; falha de configuração não recebe cache de sucesso." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Aasa" }, "example": { "applinks": { "apps": [], "details": [] } } } } }, "404": { "description": "Pode ter corpo vazio; não presumir envelope administrativo. Consulte o guia público." }, "405": { "description": "Pode ter corpo vazio; não presumir envelope administrativo. Consulte o guia público." }, "503": { "description": "Pode ter corpo vazio; não presumir envelope administrativo. Consulte o guia público." } } } } }, "components": { "schemas": { "NativeResolution": { "$ref": "#/components/schemas/resolution.schema" }, "NativeEvent": { "type": "object", "properties": { "eventId": { "type": "string", "format": "uuid", "pattern": "^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$" }, "type": { "enum": [ "app_open", "content_view" ] }, "linkId": { "type": "string", "maxLength": 650 }, "openId": { "type": "string", "format": "uuid", "pattern": "^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$" }, "parentEventId": { "type": "string", "format": "uuid", "pattern": "^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$" }, "occurredAt": { "type": "string", "format": "date-time" }, "platform": { "enum": [ "ios", "android" ] }, "entryMethod": { "enum": [ "https", "scheme_envelope", "explicit_clipboard", "app_clip" ] }, "campaign": { "type": "object", "properties": { "utm_source": { "type": "string", "maxLength": 200 }, "utm_medium": { "type": "string", "maxLength": 200 }, "utm_campaign": { "type": "string", "maxLength": 200 }, "utm_term": { "type": "string", "maxLength": 200 }, "utm_content": { "type": "string", "maxLength": 200 } }, "required": [], "additionalProperties": false } }, "required": [ "eventId", "type", "linkId", "openId", "occurredAt", "platform", "entryMethod" ], "additionalProperties": false, "allOf": [ { "if": { "properties": { "type": { "const": "content_view" } }, "required": [ "type" ] }, "then": { "required": [ "parentEventId" ] }, "else": { "not": { "required": [ "parentEventId" ] } } } ] }, "NativeBatch": { "type": "object", "properties": { "version": { "const": 1 }, "appId": { "type": "string", "maxLength": 200, "minLength": 1 }, "events": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "$ref": "#/components/schemas/NativeEvent" } } }, "required": [ "version", "appId", "events" ], "additionalProperties": false }, "NativeAck": { "type": "object", "properties": { "version": { "const": 1 }, "results": { "type": "array", "maxItems": 20, "items": { "type": "object", "properties": { "eventId": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "status": { "enum": [ "accepted", "duplicate", "retry", "rejected" ] }, "reason": { "enum": [ "invalid_event", "conflict", "unavailable_link", "parent_missing", "rate_limited" ] } }, "required": [ "eventId", "status" ], "additionalProperties": false } }, "retryAfterSeconds": { "type": "integer", "minimum": 1 } }, "required": [ "version", "results" ], "additionalProperties": false }, "PublicError": { "type": "object", "properties": { "version": { "const": 1 }, "code": { "type": "string", "maxLength": 200 }, "message": { "type": "string", "maxLength": 1000 }, "policyVersion": { "type": "string", "maxLength": 200 } }, "required": [ "code" ], "additionalProperties": true }, "RecoveryRead": { "type": "object", "properties": { "version": { "const": 1 }, "appId": { "type": "string", "maxLength": 200, "minLength": 1 }, "token": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } }, "required": [ "version", "appId", "token" ], "additionalProperties": true }, "RecoveryRedeem": { "type": "object", "properties": { "version": { "const": 1 }, "appId": { "type": "string", "maxLength": 200, "minLength": 1 }, "token": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "claimId": { "type": "string", "format": "uuid", "pattern": "^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$" } }, "required": [ "version", "appId", "token", "claimId" ], "additionalProperties": true }, "RecoveryStage": { "type": "object", "properties": { "version": { "const": 1 }, "appId": { "type": "string", "maxLength": 200, "minLength": 1 }, "token": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "eventId": { "type": "string", "format": "uuid", "pattern": "^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$" }, "stage": { "enum": [ "page_presented", "copied", "store_choice", "clip_preview" ] } }, "required": [ "version", "appId", "token", "eventId", "stage" ], "additionalProperties": true }, "RecoveryResult": { "type": "object", "properties": { "version": { "const": 1 }, "appId": { "type": "string", "maxLength": 200, "minLength": 1 }, "linkId": { "type": "string", "maxLength": 650 }, "context": { "type": "object", "properties": { "publicUri": { "type": "string", "format": "uri" } }, "required": [ "publicUri" ], "additionalProperties": true }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "version", "appId", "linkId", "context", "expiresAt" ], "additionalProperties": false }, "RecoveryStageAck": { "type": "object", "properties": { "accepted": { "type": "boolean" } }, "required": [ "accepted" ], "additionalProperties": false }, "DetectionSignals": { "type": "object", "properties": { "platform": { "const": "ios" }, "family": { "enum": [ "iphone", "ipad" ] }, "osVersion": { "type": "string", "pattern": "^\\d{1,2}(?:[._]\\d{1,2}){0,2}$" }, "language": { "type": "string", "maxLength": 40 }, "timezone": { "type": "string", "maxLength": 80 }, "screen": { "type": "object", "properties": { "width": { "type": "number", "minimum": 200, "maximum": 3000 }, "height": { "type": "number", "minimum": 200, "maximum": 3000 }, "scale": { "type": "number", "minimum": 1, "maximum": 5 }, "gamut": { "enum": [ "srgb", "p3", "rec2020", "unknown" ] } }, "required": [ "width", "height", "scale" ], "additionalProperties": false }, "languages": { "type": "array", "maxItems": 5, "minItems": 1, "items": { "type": "string", "maxLength": 40 } }, "preferences": { "type": "object", "properties": { "colorScheme": { "enum": [ "light", "dark", "unknown" ] }, "reducedMotion": { "type": [ "boolean", "null" ] }, "contrast": { "enum": [ "standard", "more", "less", "unknown" ] } }, "required": [], "additionalProperties": false } }, "required": [ "platform", "family", "osVersion", "language", "timezone" ], "additionalProperties": false }, "DetectionChallenge": { "type": "object", "properties": { "appId": { "type": "string", "maxLength": 200, "minLength": 1 }, "kind": { "enum": [ "click", "attempt" ] }, "linkId": { "type": "string", "maxLength": 650 } }, "required": [ "appId", "kind" ], "additionalProperties": true, "allOf": [ { "if": { "properties": { "kind": { "const": "click" } }, "required": [ "kind" ] }, "then": { "required": [ "linkId" ] } } ] }, "DetectionChallengeResult": { "type": "object", "properties": { "version": { "const": 1 }, "nonce": { "type": "string", "format": "uuid", "pattern": "^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$" }, "challenge": { "type": "string", "maxLength": 2000 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "version", "nonce", "challenge", "expiresAt" ], "additionalProperties": false }, "DetectionClick": { "type": "object", "properties": { "appId": { "type": "string", "maxLength": 200, "minLength": 1 }, "challenge": { "type": "string", "maxLength": 2000 }, "signals": { "$ref": "#/components/schemas/DetectionSignals" } }, "required": [ "appId", "challenge", "signals" ], "additionalProperties": true }, "DetectionIntent": { "type": "object", "properties": { "appId": { "type": "string", "maxLength": 200, "minLength": 1 }, "intentReceipt": { "type": "string", "maxLength": 2000 } }, "required": [ "appId", "intentReceipt" ], "additionalProperties": true }, "DetectionAttempt": { "type": "object", "properties": { "appId": { "type": "string", "maxLength": 200, "minLength": 1 }, "challenge": { "type": "string", "maxLength": 2000 }, "attemptId": { "type": "string", "format": "uuid", "pattern": "^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$" }, "signals": { "$ref": "#/components/schemas/DetectionSignals" } }, "required": [ "appId", "challenge", "attemptId", "signals" ], "additionalProperties": true }, "DetectionClaim": { "type": "object", "properties": { "appId": { "type": "string", "maxLength": 200, "minLength": 1 }, "receipt": { "type": "string", "maxLength": 1500 }, "confirmed": { "type": "boolean" } }, "required": [ "appId", "receipt", "confirmed" ], "additionalProperties": true }, "DetectionCaptureAck": { "type": "object", "properties": { "version": { "const": 1 }, "mode": { "const": "detection" }, "accepted": { "type": "boolean" }, "intentReceipt": { "type": "string", "maxLength": 2000 } }, "required": [ "version", "mode", "accepted" ], "additionalProperties": false }, "DetectionResult": { "type": "object", "properties": { "version": { "const": 1 }, "mode": { "const": "detection" }, "status": { "enum": [ "candidate", "confirm_candidate", "ambiguous", "no_match" ] }, "policyVersion": { "type": "string", "maxLength": 200 }, "reason": { "type": "string", "maxLength": 200 }, "candidate": { "type": "object", "properties": { "clickId": { "type": "string", "format": "uuid", "pattern": "^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$" }, "linkId": { "type": "string", "maxLength": 650 }, "publicUri": { "type": "string", "format": "uri" }, "score": { "type": "integer", "minimum": 0, "maximum": 100 } }, "required": [ "clickId", "linkId", "publicUri", "score" ], "additionalProperties": false }, "receipt": { "type": "string", "maxLength": 1500 } }, "required": [ "version", "mode", "status", "policyVersion" ], "additionalProperties": false }, "DetectionClaimResult": { "type": "object", "properties": { "version": { "const": 1 }, "mode": { "const": "detection" }, "policyVersion": { "type": "string", "maxLength": 200 }, "publicUri": { "type": "string", "format": "uri" }, "linkId": { "type": "string", "maxLength": 650 }, "attemptId": { "type": "string", "format": "uuid", "pattern": "^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$" } }, "required": [ "version", "mode", "policyVersion", "publicUri", "linkId", "attemptId" ], "additionalProperties": false }, "AssetLinks": { "type": "array", "items": { "type": "object", "properties": { "relation": { "type": "array", "items": { "type": "string", "maxLength": 200 } }, "target": { "type": "object", "properties": { "namespace": { "const": "android_app" }, "package_name": { "type": "string", "maxLength": 255 }, "sha256_cert_fingerprints": { "type": "array", "items": { "type": "string", "maxLength": 95 } } }, "required": [ "namespace", "package_name", "sha256_cert_fingerprints" ], "additionalProperties": false } }, "required": [ "relation", "target" ], "additionalProperties": true } }, "Aasa": { "type": "object", "properties": { "applinks": { "type": "object", "properties": { "apps": { "type": "array", "items": { "type": "string", "maxLength": 200 } }, "details": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "required": [ "details" ], "additionalProperties": true } }, "required": [ "applinks" ], "additionalProperties": true }, "resolution.schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://agilink.io/contracts/native-links/v1/resolution.schema.json", "title": "Agilink resolution v1", "type": "object", "required": [ "version", "link" ], "additionalProperties": false, "properties": { "version": { "const": 1 }, "link": { "type": "object", "required": [ "id", "appId", "domain", "prefix", "slug", "appPath", "title", "description", "imageUrl", "webUrl", "webOnly", "parameters" ], "additionalProperties": false, "properties": { "id": { "type": "string" }, "appId": { "type": "string" }, "domain": { "type": "string" }, "prefix": { "type": "string" }, "slug": { "type": "string" }, "appPath": { "type": [ "string", "null" ], "maxLength": 2048 }, "title": { "type": [ "string", "null" ], "maxLength": 1000 }, "description": { "type": [ "string", "null" ], "maxLength": 4000 }, "imageUrl": { "type": [ "string", "null" ], "maxLength": 4096 }, "webUrl": { "type": [ "string", "null" ], "maxLength": 4096 }, "webOnly": { "type": "boolean" }, "parameters": { "type": "object" } }, "allOf": [ { "if": { "properties": { "webOnly": { "const": true } } }, "then": { "properties": { "webUrl": { "type": "string", "minLength": 1 } } } } ] } } } } } }