Do seu ERP à impressora do cliente, sem construir uma infraestrutura de impressão.

Se você está conhecendo o Native agora, siga esta ordem. Ela representa o Golden Path de uma integração comercial.

1. Confirme a API. Chame GET /managed/health e GET /managed/capabilities.
2. Crie ou reconcilie o cliente. Use POST /accounts com um external_id estável do seu ERP.
3. Gere o vínculo. Crie um enrollment temporário e entregue somente ao Agent daquele cliente.
4. Aguarde a sincronização. Depois do Agent online, liste devices e printers.
5. Envie o job. Use Idempotency-Key única para evitar duplicidade.
6. Acompanhe o resultado. Consulte o job até printed ou failed.

export PRINT_STA_TOKEN="pst_live_SUA_CREDENCIAL"
BASE="https://api.print-sta.com.br/v1"
AUTH="Authorization: Bearer $PRINT_STA_TOKEN"

# 1) validar contrato
curl -sS "$BASE/managed/health" -H "$AUTH"
curl -sS "$BASE/managed/capabilities" -H "$AUTH"

# 2) criar/reconciliar cliente
ACCOUNT=$(curl -sS -X POST "$BASE/accounts" \
  -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"external_id":"tenant-123","display_name":"Loja Exemplo"}')

# 3) use data.account_id para gerar enrollment
# 4) após Agent online, liste printers
# 5) envie POST /accounts/{account_id}/jobs com Idempotency-Key

const BASE = "https://api.print-sta.com.br/v1";
const TOKEN = process.env.PRINT_STA_TOKEN;
async function native(path, init = {}) {
  const response = await fetch(BASE + path, {
    ...init,
    headers: { Authorization: `Bearer ${TOKEN}`, "Content-Type": "application/json", ...init.headers }
  });
  const body = await response.json();
  if (!response.ok) throw new Error(`${response.status} ${body.code}: ${body.message}`);
  return body;
}
const account = await native("/accounts", {
  method: "POST",
  body: JSON.stringify({ external_id: "tenant-123", display_name: "Loja Exemplo" })
});
console.log(account.data.account_id);

import os, requests
BASE = "https://api.print-sta.com.br/v1"
H = {"Authorization": f"Bearer {os.environ['PRINT_STA_TOKEN']}"}
r = requests.post(BASE + "/accounts", headers=H,
  json={"external_id":"tenant-123", "display_name":"Loja Exemplo"})
r.raise_for_status()
print(r.json()["data"]["account_id"])

A credencial define no servidor o Partner, a Application, o ambiente e os scopes. O payload nunca deve tentar substituir essa autoridade.

POST /accounts reconcilia o tenant do seu sistema com uma Account Native. Use um external_id estável do seu ERP e guarde o account_id retornado.

POST /v1/accounts
{
  "external_id": "tenant-123",
  "display_name": "Loja Exemplo"
}

200 ACCOUNT_PROVISIONED
{
  "data": {
    "account_id": "<uuid-opaco>",
    "external_id": "tenant-123",
    "status": "active"
  }
}

Seu ERP solicita um token temporário e o entrega ao Agent. O token é de uso único, expira rapidamente e não substitui a credencial Partner.

POST /v1/accounts/{account_id}/enrollments
{"ttl_seconds":600}

201 ENROLLMENT_CREATED
{
  "data": {
    "enrollment_token": "pstenr_..."
  }
}

GET /accounts/{account_id}/devices lista os computadores. POST /accounts/{account_id}/devices/{device_id}/deactivate revoga um vínculo específico.

Printers pertencem a um device da Account. Use o estado retornado pela API em vez de recriar lógica de disponibilidade no ERP.

POST/PATCH usam application/json. X-Correlation-Id é opcional; quando enviado, deve ter 8–128 caracteres seguros. Registre sempre request/correlation IDs no seu observability stack.

Listagens retornam items, has_more e next_cursor. Reenvie o cursor exatamente como recebido.

A infraestrutura Partner-scoped de webhook provisioning/delivery está evoluindo no dev, mas a Partner API estável ainda publica features.webhooks=false.

Partner API v1 é o contrato externo. Mudanças compatíveis podem adicionar campos; o consumidor deve ignorar campos desconhecidos. Breaking changes exigem nova versão de contrato. O OpenAPI e o llms.txt devem acompanhar a superfície implementada.