--- name: principia-apis description: Responde dúvidas e faz chamadas às APIs públicas da Principia para integradores, a API de Integração da IES (alunos, parcelas, processamento, liquidações, acordos, extratos, SSO) e a API do PrincipiaPay Checkout v4 (vendas/checkout, webhooks, cursos, turmas, status). Lê a documentação oficial em docs.ies.integracao.principia.net antes de responder. Use when alguém perguntar como integrar com a Principia ou com o PrincipiaPay, pedir exemplo de requisição, payload, erro ou evento de webhook dessas APIs, ou quiser testar uma chamada em homologação. --- # APIs da Principia para integradores Esta skill ajuda você (ou o seu agente) a integrar com as duas APIs públicas da Principia. A fonte da verdade é sempre a documentação oficial em `https://docs.ies.integracao.principia.net`. Esta skill diz **onde ler** e **como chamar**; o conteúdo detalhado está no site. ## 1. Descubra qual API é | Se a pessoa fala de... | API | Autenticação | Base URL (homologação / produção) | | --- | --- | --- | --- | | aluno, parcela, boleto da IES, lote, liquidação, acordo, extrato, SSO | **API de Integração (IES)** | header `apikey: ` | `https://api-staging.principia.services/api-integracao` / `https://api.principia.services/api-integracao` | | checkout, venda, `POST /sales`, produto/variação, curso/turma, webhook de compra, parceiro | **PrincipiaPay (Checkout v4)** | header `Api-Token: ` | `https://app-staging.principia.services/checkout/v4` / `https://app.principia.services/checkout/v4` | Se não der para saber, pergunte antes de responder. ## 2. Leia a documentação antes de responder Nunca responda de memória nem invente rota, campo ou código de erro. Busque a página certa: - **Índice de todas as páginas:** `https://docs.ies.integracao.principia.net/llms.txt` - **Toda a documentação em um arquivo:** `https://docs.ies.integracao.principia.net/llms-full.txt` (grande; prefira a página específica) - **Uma página em Markdown:** troque `/docs/` por `/llms.mdx/docs//content.md`. Exemplos: - `https://docs.ies.integracao.principia.net/llms.mdx/docs/autenticacao/content.md` - `https://docs.ies.integracao.principia.net/llms.mdx/docs/principiapay/webhooks/content.md` Páginas mais usadas: | Assunto | IES | PrincipiaPay | | --- | --- | --- | | Primeiros passos / visão geral | `/docs/quickstart` | `/docs/principiapay` | | Autenticação | `/docs/autenticacao` | `/docs/principiapay/autenticacao` | | Ambientes e URLs | `/docs/ambientes` | `/docs/principiapay/ambientes` | | Fluxo de ponta a ponta | `/docs/fluxo` | `/docs/principiapay/fluxo` | | Erros | `/docs/erros` | `/docs/principiapay/erros` | | Perguntas frequentes | `/docs/faq` | `/docs/principiapay/faq` | | Assuntos específicos | `/docs/sso`, `/docs/acordos`, `/docs/liquidacoes` | `/docs/principiapay/checkout`, `/docs/principiapay/webhooks`, `/docs/principiapay/status` | A referência de cada rota (parâmetros, corpo, respostas) fica em `/docs/api/...` (IES) e `/docs/principiapay/api/...` (PrincipiaPay); encontre o caminho exato pelo `llms.txt`. Ao responder, cite a página usada (URL) para a pessoa conferir. ## 3. Pegadinhas que mais confundem **API de Integração (IES)** - Inclusão de alunos e parcelas é **assíncrona**: `201` só quer dizer que o lote foi recebido. A validação vem depois; acompanhe o lote nas rotas de processamento e reenvie só os itens que falharam. - Envie sempre dentro de um array (`alunos`, `parcelas`), mesmo com um item. - "Não encontrado" **não é 404**: várias consultas devolvem `200` com `[]` ou campos `null`. Verifique o corpo, não o status. - `idParcela` é a chave da parcela (upsert): mesmo `idParcela` atualiza, novo cria. - Depois de enviar uma parcela à Principia, a IES não pode manter boleto próprio para ela (cobrança em duplicidade). **PrincipiaPay (Checkout v4)** - `POST /sales` cria uma venda nova a cada chamada; o `externalSaleId` não impede duplicata. Não repita a chamada às cegas depois de timeout: consulte antes por `GET /sales/external-purchase/{externalSaleId}`. - As consultas de venda devolvem **lista**, e os produtos voltam com `productSKU`/`variantSKU` (SKU maiúsculo), diferente do corpo de criação (`productSku`/`variantSku`). - Produto é identificado pelo `productSku`; variação pelo `variantSku` **e** preço. Mudar o nome não atualiza o cadastro. - O campo `status` da venda vem em português com grafia exata (ex.: `Não acessado`, `Aguardando pagamento`, `Efetivado`); compare pelo texto da página de Status. - A fonte de verdade do estado da venda são os **webhooks** (ex.: `purchaseConfirmed`), não a volta do comprador ao site. Webhooks podem chegar repetidos (até 4 reenvios): processe de forma idempotente. ## 4. Fazer chamadas (opcional) Só faça chamadas se a pessoa pedir e tiver a própria credencial. Regras: 1. **Credencial só por variável de ambiente.** Nunca peça para colar a chave no chat, nunca escreva a chave em arquivo, log ou resposta. - IES: `PRINCIPIA_IES_APIKEY` - PrincipiaPay: `PRINCIPIA_PAY_API_TOKEN` Se a variável não existir, pare e explique como criá-la (`export PRINCIPIA_PAY_API_TOKEN=...` no terminal da pessoa). 2. **Homologação por padrão.** Use produção só se a pessoa pedir explicitamente, e avise que a chamada tem efeito real. 3. **Leitura antes de escrita.** Comece por uma rota que não altera nada. Antes de qualquer `POST`, `PUT`, `PATCH` ou `DELETE`, mostre o comando e peça confirmação. Primeira chamada para validar a credencial (só leitura): ```bash # IES curl -sS "https://api-staging.principia.services/api-integracao/v1/parcela/originais" \ -H "apikey: $PRINCIPIA_IES_APIKEY" # PrincipiaPay: devolve os dados do parceiro dono do token curl -sS "https://app-staging.principia.services/checkout/v4/seller" \ -H "Api-Token: $PRINCIPIA_PAY_API_TOKEN" ``` `401` nas duas quer dizer credencial ausente, errada ou de outro ambiente (homologação e produção têm credenciais diferentes). Veja a página de Erros de cada API. ## 5. Quando não souber Se a documentação não cobrir a dúvida, diga isso claramente e indique o contato: `suporte-tecnologia@provi.com.br` (PrincipiaPay) ou o time de integração da Principia (IES, `processamento@principia.net`).