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_...oupi_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/:tokenou/d/:slug) para os dispositivos dos utilizadores finais.
URLs Base e Documentação OpenAPI Interativa
| Recurso / Ambiente | URL | Descrição |
|---|---|---|
| URL Base da API de Produção | https://api.passinstance.com/api/v1 | Emissão em espaços de trabalho de produção, atualizações push de carteira e leitura em produção. |
| URL Base de Staging / Sandbox | https://staging-api.passinstance.com/api/v1 | Ambiente isolado de testes de pré-produção. |
| Swagger UI Interativo Público | GET https://api.passinstance.com/api/public/docs | Especificação OpenAPI 3.0 filtrada para programadores externos em todos os ambientes. |
| Swagger UI Completo de Não Produção | GET /api/docs | Interface 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):
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 Credencial | Cabeçalho HTTP | Prefixo / Formato do Token | Superfície Permitida |
|---|---|---|---|
| Chave de API de Produção | Authorization: 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 Sandbox | Authorization: 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.0 | Authorization: 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 Leitura | x-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étodo | Endpoint | Permissão Necessária (api-key-permissions) | Descrição |
|---|---|---|---|
| GET | /api/v1/api-keys | api:keys-read ou api:keys-manage | Lista todas as chaves de API ativas (e opcionalmente ?includeInactive=true) com valores key mascarados. |
| GET | /api/v1/api-keys/:id | api:keys-read ou api:keys-manage | Obtém metadados de uma única chave de API por UUID. |
| POST | /api/v1/api-keys | api:keys-manage | Cria 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/:id | api:keys-manage | Atualiza o name, scopes ou expiresAt da chave (request payload). |
| DELETE | /api/v1/api-keys/:id | api:keys-manage | Elimina permanentemente uma chave de API e regista uma entrada API_KEY_DELETED no registo de auditoria. |
| POST | /api/v1/api-keys/:id/regenerate | api:keys-manage | Gera um novo token secreto preservando o id, name e scopes da chave. |
| POST | /api/v1/api-keys/:id/activate | api:keys-manage | Reativa imediatamente uma chave de API previamente desativada. |
| POST | /api/v1/api-keys/:id/deactivate | api:keys-manage | Desativa de forma reversível uma chave de API (carimbo de data/hora archivedAt) sem perder a configuração. |
| POST | /api/v1/api-keys/:id/test | api:keys-manage | Verifica a configuração e o estado de validade da chave (API key verification result). |
| GET | /api/v1/api-keys/:id/usage | api:keys-read ou api:keys-manage | Devolve 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 porexternalIde transferências.pkpassporbundleId). -
'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)
{
"name": "Shopify Checkout Issuance Worker",
"environment": "live",
"scopes": ["passes", "templates"],
"expiresAt": "2027-11-16T00:00:00.000Z"
}
Resposta (201 Created):
{
"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 resposta201 Createdou/regenerate. As chamadas subsequentes aGET /api/v1/api-keysdevolvem um prefixo mascarado emkey.
Explore o catálogo completo de endpoints em Referência da API e as especificações interativas em /docs.
