Portal do Parceiro

Do cadastro à produção

O caminho de uma integração nova tem seis etapas. As três primeiras você faz sozinho, em minutos; as demais dependem de aprovação.

1. 1

   Crie a conta

   Cadastre-se no portal e confirme o e-mail. O acesso ao painel só é liberado depois da confirmação.

2. 2

   Crie um app

   Cada integração é um app, com chaves, conexões, webhooks e logs próprios. O app nasce no status Sandbox.

3. 3

   Teste no sandbox

   Na aba Credenciais, gere uma chave toaqui_test_… e chame a API com a escola de demonstração. Nada do que você faz ali chega à produção.

4. 4

   Peça a aprovação para produção

   Na aba Visão geral, descreva como o app usa a API: quais dados lê e grava, com que frequência, quem são os usuários finais e como os dados de alunos são protegidos (LGPD). A equipe To Aqui revisa cada app e você recebe a decisão por e-mail.

5. 5

   Peça acesso a cada cliente

   Aprovado o app, informe na aba Clientes o CNPJ de uma escola do cliente que contratou a sua integração. A equipe To Aqui confirma com o cliente e libera o acesso.

6. 6

   Gere o token da conexão

   Com o acesso liberado, gere uma chave toaqui_live_… e o token da conexão com aquele cliente. A partir daí o app chama a API com os dados reais da escola.

Sandbox e produção

O sandbox é uma instância separada da To Aqui Escola, com banco de dados, filas e arquivos próprios, em https://sandbox.toakiescola.com.br. Chaves de teste só funcionam lá; chaves de produção só funcionam em produção. Os endpoints e o formato das respostas são os mesmos nos dois.

• Toda resposta traz o cabeçalho X-ToAqui-Environment (test ou live) e os cabeçalhos X-RateLimit-*. O limite é contado por app e por ambiente.
• Na aba Credenciais, crie o cliente de teste da rede privada e/ou da rede pública (SEDUC). Cada um vem com uma escola, o Colégio Demonstração, com dados em todos os módulos da referência da API: turmas, alunos, responsáveis, professores, notas, frequência, diário, conselho de classe, ocorrências, fotos e os módulos de ERP (financeiro, CRM e RH só na rede privada).
• O quadro Dados de teste de cada cliente traz um valor pronto para cada parâmetro dos endpoints (CNPJ, turma, matrícula, CPF, aula, nota…) e o ID de um registro de cada recurso endereçado por {id}.
• Os clientes de teste são só do seu app: nenhum outro parceiro os vê, e os dados ficam como você deixou. Para voltar ao estado inicial, use "Recriar dados" — o cliente é apagado e criado de novo, com novo X-Client, X-Authorization e login.
• No sandbox, pagamentos e assinaturas eletrônicas são simulados: o link de uma cobrança abre uma página onde você "paga" (PIX, boleto ou cartão), e o link de assinatura abre uma página onde você "assina". A escola recebe a confirmação como receberia em produção, e os webhooks correspondentes são enviados.
• Uma chave de teste usada em produção recebe 403 com "code": "SANDBOX_HOST" e o endereço do sandbox.

Primeira chamada no sandbox

Com uma chave de teste e o slug e o token de um cliente de teste copiados da aba Credenciais, liste as escolas desse cliente no sandbox:

use GuzzleHttp\Client;

$client = new Client();

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

$environment = $response->getHeaderLine('X-ToAqui-Environment'); // "test"

const response = await fetch('https://sandbox.toakiescola.com.br/api/v1/partners/schools/all', {
    headers: {
        'X-Partner':       'toaqui_test_{sua_chave}',
        'X-Client':        '{slug_do_cliente_de_teste}',
        'X-Authorization': '{token_do_cliente_de_teste}',
    },
});

const environment = response.headers.get('X-ToAqui-Environment'); // "test"

Para ir à produção, troque os três valores: a chave toaqui_live_…, o slug do cliente e o token da conexão, ambos mostrados na aba Clientes. O código da integração não muda.

Status do app

Chaves de teste funcionam em qualquer status, exceto quando o app está suspenso. Chaves de produção só funcionam com o app em Produção.

Um app, ou a conta inteira do desenvolvedor, pode ser suspenso pela equipe To Aqui. Enquanto estiver suspenso, todas as chaves respondem 403, inclusive as de teste.

Chaves e tokens

Erros de acesso

Além dos erros gerais da API, requisições feitas com chaves do portal podem receber: