❮ Integrações

API para organizações

O seu cliente concede acesso à sua empresa e a sua aplicação ganha um botão Abrir. Nenhuma chave circula por conversas e cada abertura leva o nome do funcionário que carregou.

Para quem: serviços cujo funcionário tem de entrar num pátio fechado — amas e explicadores, limpeza, pneus e lavagem móveis, estafetas e entregas, enfermagem e análises ao domicílio. O cliente mantém a cancela que já tem; você ganha um botão em vez de um telefonema ao cliente ao portão.

Como funciona

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.
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.
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.

A chave não existe como ligação. A sua empresa recebe uma referência a ela, não a própria chave — não há nada para copiar ou reenviar; a chave está ligada à sua conta e só funciona por esta API. Passar o acesso a um funcionário não é possível — é propositado, e é por isso que o cliente o concede descansado.

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 within a day. There is no one-off "verified" tick to outlive reality.

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

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

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 hex, 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.

A secret, if you have no domain

Register, issue a secret in the cabinet and put it in the body. Your calls work the same, but the client is shown only the name you wrote for yourself, with a note that the domain is not confirmed — no logo, no domain. A company that has set a domain can no longer use a secret: otherwise a leaked secret would speak in the name of a confirmed one.

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

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

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" }

Estado	Meaning
`new`	o código QR foi criado, o cliente ainda não chegou
`claimed`	o cliente abriu a aplicação — está a caminho
`issued`	acesso concedido; `key_ref` é com isso que abre
`revoked`	o cliente retirou o acesso
`expired`	o pedido expirou antes de o cliente chegar

Abertura

POST /api/company.php?a=open
{ "org_id": 17, "secret": "…", "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.

Resposta	Meaning
`403 forbidden`	a chave não é sua ou o objeto não está nela
`403 revoked`	o cliente retirou o acesso
`403 expired`	o tempo de vida da chave terminou
`400 actor_required`	o funcionário não foi indicado
`429 rate_limit`	demasiadas aberturas com uma chave por minuto

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.

Como começar

Registe a empresa na sua conta: o pedido e depois o segredo, o endereço de retorno, o logótipo e a lista de pedidos — tudo no painel da empresa. Analisamos os pedidos à mão: o cliente confia na empresa que deixamos entrar na lista.

Painel da empresa