Skip to content
Guia da Central de Ajuda · API de programador
5 min de leituraVerificado 2026-11-16

Visão geral e autenticação da API

URLs base (api.passinstance.com/api/v1), chaves API vs tokens de Scanner/SDK, cabeçalhos e limites.

Neste guia

Visão Geral

A API REST do Passinstance permite a emissão de passes servidor-a-servidor, gestão de modelos, mutações de saldo em tempo real, orquestração de webhooks e extração de analítica. Todos os endpoints padrão estão montados sob o caminho base versionado https://api.passinstance.com/api/v1, aceitam e devolvem JSON UTF-8 (Content-Type: application/json) e encapsulam as respostas padrão num envelope determinístico API response (T).

Importante: Nunca incorpore chaves de API do espaço de trabalho (pi_live_... ou pi_test_...) em JavaScript de navegador do lado do cliente, binários de aplicações móveis ou repositórios Git públicos. Invoque sempre a API do Passinstance a partir do seu servidor de backend e transmita apenas o URL inteligente de transferência resultante (/s/:token ou /d/:slug) para os dispositivos dos utilizadores finais.

URLs Base e Documentação OpenAPI Interativa

Recurso / AmbienteURLDescrição
URL Base da API de Produçãohttps://api.passinstance.com/api/v1Emissão em espaços de trabalho de produção, atualizações push de carteira e leitura em produção.
URL Base de Staging / Sandboxhttps://staging-api.passinstance.com/api/v1Ambiente isolado de testes de pré-produção.
Swagger UI Interativo PúblicoGET https://api.passinstance.com/api/public/docsEspecificação OpenAPI 3.0 filtrada para programadores externos em todos os ambientes.
Swagger UI Completo de Não ProduçãoGET /api/docsInterface Swagger completa interna gerada em ambientes de não produção (também incorporada em /settings/workspace/developer no Painel de Controlo).

Arquitetura de Autenticação e Regras de Ambiente

O Passinstance impõe uma separação rigorosa do raio de impacto em três famílias de credenciais (API Key Authentication, OAuth 2.0 Authentication e Scanner Key Authentication):

FLUXO DE ARQUITETURA
ARQUITETURA INTERATIVA
AUTENTICAÇÃO DA API E VERIFICAÇÃO DE ÂMBITO
ATORES DE SISTEMA PARTICIPANTES
P1 Cliente / Servidor Backend
P2 Gateway de API e Guardas Auth
P3 Controlador de Destino
ETAPA 1a PEDIDO / AÇÃO Authorization: ApiKey
›
(API Key Authentication)
›
pi_live_...
›
Verificar hash, expiração
›
e ambiente (test vs live)
›
Validar API_KEY_SCOPE_VALUES
›
(passes, templates, scans,
ETAPA 1b PEDIDO / AÇÃO x-api-key: pi_live_...
›
webhooks, analytics, *)
ETAPA 1c PEDIDO / AÇÃO x-scanner-key: <key>
›
(Scanner Key Authentication)
›
Restringir a /api/v1/scans
›
& /api/v1/scanner-keys
ETAPA 2 PEDIDO / AÇÃO Impor Isolamento Tenant
ETAPA 3 RESPOSTA 200 OK API response (T)
›
<-------------------------------

Cabeçalhos de Autenticação Suportados e API_KEY_ENVIRONMENT_VALUES

request payload.environment utiliza API_KEY_ENVIRONMENT_VALUES ('test' | 'live'). As chaves de sandbox (pi_test_...) são válidas apenas em espaços de trabalho de sandbox, enquanto as chaves de produção (pi_live_...) são válidas apenas em espaços de trabalho de produção:

Tipo de CredencialCabeçalho HTTPPrefixo / Formato do TokenSuperfície Permitida
Chave de API de ProduçãoAuthorization: ApiKey pi_live_... ou x-api-key: pi_live_...pi_live_<secret> (environment: "live")Chamadas à API do espaço de trabalho de produção que correspondam aos API_KEY_SCOPE_VALUES atribuídos.
Chave de API de SandboxAuthorization: ApiKey pi_test_... ou x-api-key: pi_test_...pi_test_<secret> (environment: "test")Testes em espaço de trabalho de sandbox e suítes automatizadas de integração CI/CD.
Token Bearer OAuth 2.0Authorization: Bearer <jwt>JWT assinado (OAuth 2.0 Authentication + Permission Scope Validation)Plataformas iPaaS ligadas (Zapier, Make) que utilizam âmbitos OAuth granulares (webhooks:read, webhooks:write, templates:read).
Chave de Dispositivo de Leiturax-scanner-key: <scanner-key><scanner-key> (Scanner Key Authentication)Estritamente isolada para /api/v1/scans, /api/v1/scanner-keys e rotas de leitura de mecânicas.

Gestão de Chaves de API (API Keys API e Interface do Painel)

Gira as credenciais visualmente em Definições do Espaço de Trabalho -> Programador -> Credenciais de API (/settings/workspace/developer/api-credentials, ou /platform/api-keys) ou programaticamente através de /api/v1/api-keys:

MétodoEndpointPermissão Necessária (api-key-permissions)Descrição
GET/api/v1/api-keysapi:keys-read ou api:keys-manageLista todas as chaves de API ativas (e opcionalmente ?includeInactive=true) com valores key mascarados.
GET/api/v1/api-keys/:idapi:keys-read ou api:keys-manageObtém metadados de uma única chave de API por UUID.
POST/api/v1/api-keysapi:keys-manageCria uma nova chave de API pi_live_ ou pi_test_ (request payload); devolve a key em texto simples uma única vez.
PATCH / PUT/api/v1/api-keys/:idapi:keys-manageAtualiza o name, scopes ou expiresAt da chave (request payload).
DELETE/api/v1/api-keys/:idapi:keys-manageElimina permanentemente uma chave de API e regista uma entrada API_KEY_DELETED no registo de auditoria.
POST/api/v1/api-keys/:id/regenerateapi:keys-manageGera um novo token secreto preservando o id, name e scopes da chave.
POST/api/v1/api-keys/:id/activateapi:keys-manageReativa imediatamente uma chave de API previamente desativada.
POST/api/v1/api-keys/:id/deactivateapi:keys-manageDesativa de forma reversível uma chave de API (carimbo de data/hora archivedAt) sem perder a configuração.
POST/api/v1/api-keys/:id/testapi:keys-manageVerifica a configuração e o estado de validade da chave (API key verification result).
GET/api/v1/api-keys/:id/usageapi:keys-read ou api:keys-manageDevolve telemetria de pedidos, médias de latência e distribuição de códigos de estado HTTP (API key usage summary).

Âmbitos de Chave de API Disponíveis (API_KEY_SCOPE_VALUES)

Siga o princípio do menor privilégio atribuindo apenas os âmbitos necessários a cada worker de backend (assume ["*"] por predefinição se for omitido):

  • 'passes' — Emitir, inspecionar, atualizar, anular e pesquisar instâncias de passes (incluindo pesquisas por externalId e transferências .pkpass por bundleId).
  • 'templates' — Ler esquemas de modelos, atributos personalizados e mecânicas.
  • 'scans' — Executar validações, inspecionar resultados de leituras e acionar mecânicas.
  • 'webhooks' — Gerir subscrições de webhooks e consultar filas de pull-webhooks.
  • 'analytics' — Consultar métricas de emissão de passes, registo de dispositivos e quota de carteiras.
  • '*' — Acesso administrativo total em todos os domínios da API de programador.

Criar uma Chave de API com Âmbito Definido (POST /api/v1/api-keys)

JSON
{
  "name": "Shopify Checkout Issuance Worker",
  "environment": "live",
  "scopes": ["passes", "templates"],
  "expiresAt": "2027-11-16T00:00:00.000Z"
}

Resposta (201 Created):

JSON
{
  "success": true,
  "data": {
    "id": "2c668b45-2b28-4c65-b17d-a6c7272e27ea",
    "name": "Shopify Checkout Issuance Worker",
    "key": "pi_live_89a1f4c2e90b41d7a6c3e2f10984b2c1",
    "keyPrefix": "pi_live_",
    "environment": "live",
    "scopes": ["passes", "templates"],
    "customerId": "89a12b34-56c7-4d89-9e01-23456789abcd",
    "isActive": true,
    "expiresAt": "2027-11-16T00:00:00.000Z",
    "createdAt": "2026-11-16T10:00:00.000Z"
  },
  "description": "API key created successfully",
  "errors": [],
  "statusCode": 201
}

Importante: O segredo não cifrado data.key é devolvido apenas uma vez na resposta 201 Created ou /regenerate. As chamadas subsequentes a GET /api/v1/api-keys devolvem um prefixo mascarado em key.

Explore o catálogo completo de endpoints em Referência da API e as especificações interativas em /docs.

Documentação de produto e API relacionada

Pronto para lançar o seu primeiro programa de cartões Wallet?

Crie o seu espaço de trabalho, configure o seu modelo e teste um cartão real na Apple Wallet e Google Wallet antes de escalar.