Autenticação

Para acessar qualquer endpoint da API do To Aqui Escola você deve incluir três cabeçalhos HTTP em todas as suas requisições. Esses cabeçalhos identificam o parceiro, o token de autorização e o cliente (rede escolar) sendo acessado.

Cabeçalhos obrigatórios

X-Authorization

Token de autorização

Token único fornecido ao parceiro durante o processo de onboarding. Identifica e autoriza sua integração.

X-Partner

Token do parceiro

Identificador exclusivo do parceiro no ecossistema To Aqui. Usado em conjunto com o X-Authorization.

X-Client

Slug do cliente

Identificador em texto da rede escolar (cliente) que está sendo acessada. Exemplo: colegio-exemplo.

Apps do Portal do Parceiro

Novas integrações usam os mesmos três cabeçalhos com credenciais geradas no Portal do Parceiro: crie um app, gere uma chave e teste no sandbox antes de pedir a aprovação para produção. O passo a passo completo está no guia Portal do Parceiro.

X-Partner

Chave do app. toaqui_test_… funciona somente no sandbox (https://sandbox.toakiescola.com.br/api/v1), uma instância separada da produção com os clientes de teste do app; toaqui_live_… acessa a produção e só existe depois que o app é aprovado.

X-Client

No sandbox, o slug de um dos clientes de teste do app, mostrado no portal. Em produção, o slug do cliente cujo acesso foi liberado para o app.

X-Authorization

No sandbox, o token desse cliente de teste, mostrado no portal. Em produção, o token da conexão do app com aquele cliente (toaqui_conn_…), gerado no portal depois que a equipe To Aqui libera o acesso.

Chaves e tokens são exibidos uma única vez. Guarde-os num cofre de segredos; a To Aqui armazena apenas um hash.
Toda resposta traz o cabeçalho X-ToAqui-Environment (test ou live) e os limites de requisição por minuto do app (X-RateLimit-*).
Respostas específicas: 401 chave ou token inválido/revogado, 403 app não aprovado ou suspenso (ou, com "code": "SANDBOX_HOST", chave de teste usada em produção), 429 limite excedido.

Exemplo de requisição autenticada

Adicione os três cabeçalhos em todas as chamadas à API. Substitua os valores pelos tokens fornecidos pela equipe To Aqui.

curl https://toakiescola.com.br/api/v1/partners/schools/all \
  -H "X-Authorization: dSpAucKX4JIyfkqX9sZHKFblHr92tvJD..." \
  -H "X-Partner: A6XKzcXg1rsNfI0XSENocEOBWoOnDHMa..." \
  -H "X-Client: colegio-exemplo"

use GuzzleHttp\Client;

$client = new Client();

$response = $client->get('https://toakiescola.com.br/api/v1/partners/schools/all', [
    'headers' => [
        'X-Authorization' => '{api_token}',
        'X-Partner'       => '{partner_token}',
        'X-Client'        => '{client_slug}',
    ],
]);

$data = json_decode($response->getBody(), true);

const response = await fetch('https://toakiescola.com.br/api/v1/partners/schools/all', {
    headers: {
        'X-Authorization': '{api_token}',
        'X-Partner':       '{partner_token}',
        'X-Client':        '{client_slug}',
    },
});

const data = await response.json();

Autenticação inválida

Quando um ou mais cabeçalhos estiverem ausentes ou inválidos, a API retornará um erro 401 Unauthorized.

Resposta de erro 401

{
  "message": "Unauthorized."
}