API para organizações

Como funciona

1. Na sua interface o cliente diz que é preciso entrar. Primeiro confirma duas coisas: a cancela abre com uma chamada do número dele e o telemóvel dele fica online. Se a cancela tiver um controlador Entrixy, o telemóvel não é preciso.
2. Cria um pedido e mostra o seu código QR. O cliente digitaliza, instala a aplicação, adiciona a cancela e concede o acesso — a sua empresa já está à espera na lista.
3. Abre por API, indicando o funcionário. O cliente vê a abertura no registo com esse nome e retira o acesso com um toque quando quiser.

Autenticação

There are two ways in, and the difference is what the client sees.

Signature bound to your domain

You publish a public key on your own domain and sign every call with the private one. We take the key from the domain itself, so the right to call and the right to be shown under that domain are the same thing: the file disappears, the domain moves or changes hands — the calls stop at once. There is no one-off "verified" tick to outlive reality.

https://<your domain>/.well-known/entrixy.json

{ "key": "<Ed25519 public key, 32 bytes, base64>" }

O par é criado do seu lado; a metade privada nunca a vemos. Bastam dois comandos:

openssl genpkey -algorithm ed25519 -out entrixy-private.pem
openssl pkey -in entrixy-private.pem -pubout -outform DER | tail -c 32 | base64

O segundo imprime a cadeia para o ficheiro. O primeiro deixa a chave privada consigo: assina cada chamada e não há para onde a enviar.

Then each request carries four headers:

X-Entrixy-Org:   your-domain.com
X-Entrixy-Ts:    1750000000          // unix seconds, ±300 s
X-Entrixy-Nonce: 0011…ff             // 32 lowercase hex characters, used once
X-Entrixy-Sig:   <base64>            // Ed25519 over the base string

base = "<domain>.<ts>.<nonce>." + sha256(raw request body)

A repeated nonce is refused, and so is a body that does not match the signature. This is the mode where the client sees your domain and your logo.

A domain written in national characters goes into the header and into the base string in its punycode form — xn--… — the same form it takes in the address of the key file. The client is still shown the readable spelling.

Signing in PHP, for example. openssl leaves a PEM file with a 32-byte seed, while sodium signs with the 64-byte secret key, so the first three lines derive one from the other:

$pem   = file_get_contents('entrixy-private.pem');
$der   = base64_decode(preg_replace('/-----[^-]+-----|\s+/', '', $pem));
$secretKey = sodium_crypto_sign_secretkey(sodium_crypto_sign_seed_keypair(substr($der, -32)));

$body  = json_encode($payload, JSON_UNESCAPED_UNICODE);
$ts    = time();
$nonce = bin2hex(random_bytes(16));      // 32 lowercase hex characters
$base  = "$domain.$ts.$nonce." . hash('sha256', $body);
$sig   = base64_encode(sodium_crypto_sign_detached($base, $secretKey));

Send the body exactly as it was signed, byte for byte, together with the four headers.

A call is refused before any action when the authentication does not pass:

A secret, if you have no domain

Register, issue a secret in the cabinet and put it in the body together with your company number. A secret is enough to create requests and to read their state and contents: a=request, a=status and a=objects. The client then sees only your name with a note that the domain is not confirmed — no logo, no domain.

Opening needs the domain signature. The client’s phone checks every opening of a company with the key from its domain, so a=open with a secret alone answers 401 sign_required. As soon as the key appears on your domain the secret stops working for every call: otherwise a leaked secret would speak in the name of a confirmed company.

POST https://entrixy.com/api/company.php?a=<action>
Content-Type: application/json

{ "org_id": 17, "secret": "…", … }

The examples below show the secret in the body for brevity. With the signature the same body goes without org_id and secret, and the four headers are added.

Criar um pedido

POST /api/company.php?a=request
{ "org_id": 17, "secret": "…", "ref": "order-517", "ttl_hours": 72 }

→ { "code": "rrGzNweV31rkHV6Q",
    "url":  "https://entrixy.com/c/rrGzNweV31rkHV6Q",
    "expires_in_hours": 72 }

ref é o seu número de encomenda, volta no estado. Coloque url num código QR e mostre ao cliente.

Estado do pedido

POST /api/company.php?a=status
{ "org_id": 17, "secret": "…", "code": "rrGzNweV31rkHV6Q" }

→ { "state": "issued", "key_ref": 4821, "ref": "order-517",
    "claimed_at": "2026-09-09 12:20:11", "issued_at": "2026-09-09 12:24:03" }

O que a chave abre

The answer to a=status already carries the contents of the key, and the same list comes from a=objects — by key_ref or by the request code.

POST /api/company.php?a=objects
{ "org_id": 17, "secret": "…", "key_ref": 96 }

{
  "key_ref": 96,
  "numbers": [
    { "number_id": 83, "name": "Шлагбаум во двор", "type": "call", "openable": true },
    { "number_id": 84, "name": "Ворота на парковку", "type": "call", "openable": true }
  ]
}

number_id is what you pass to a=open; it belongs to the object and does not change when the client renames it. name is the name the client gave the object and agreed to show you — the client's own names are encrypted and we do not see them, so this one arrives only because the client sent it along with the access. Until an older app is updated the field comes as null: show the visit address instead. openable is false for an object that only its holder can open — a call from the company will be refused.

When a key covers a single object, number_id no a=open may be omitted.

Abertura

POST /api/company.php?a=open
Content-Type: application/json
X-Entrixy-Org:   your-domain.com
X-Entrixy-Ts:    1750000000
X-Entrixy-Nonce: 9f86d081884c7d659a2feaa0c55ad015
X-Entrixy-Sig:   <base64>

{ "key_ref": 4821, "number_id": 93, "actor": "Ivan P., shift 12" }

→ { "ok": 1 }

actor é obrigatório: é o que o cliente vê no registo. Serve tudo o que identifique o funcionário — nome, número, turno. Sem ele a chamada é recusada.

The authentication answers from the table above apply here too.

O seu cartão na aplicação

Ao registar a empresa, envie-nos o nome e um logótipo quadrado. O cliente vê-os na página que digitaliza, no ecrã de consentimento e junto de cada linha do registo — assim sabe quem deixa entrar. O logótipo é servido por nós; não puxamos imagens de outros servidores.

Quando o cliente retira o acesso

The client removes the company in their app — the key disappears at once. a=open answers revoked, a=objects the same, and a=status shows the request as revoked with an empty list of objects. Nothing else has to be done on your side: a revoked access never comes back, a new visit needs a new request.

If you saved a callback address, we also ping it on the events — claimed, issued, revoked:

POST <your callback address>
{ "event": "revoked", "org_id": 5, "code": "eAc9SZ8mmeegD_GJ", "key_ref": 96 }

The address must start with https. The ping waits 3 seconds for an answer and does not follow redirects.

The ping is a nudge, not the source of truth: it carries no object list and is sent once, without retries. Take the details from a=status — that call is signed and answers the same thing whether the ping arrived or not.

Como começar

Registe a empresa na sua conta — é um único formulário e começa a funcionar de imediato. O domínio, o segredo, o endereço de retorno, o logótipo e a lista de pedidos estão na área da empresa.

Painel da empresa