Primeiros passos

Este guia leva você da configuração inicial até a primeira chamada bem-sucedida.

1. Tenha sua chave em mãos

Você vai precisar da sua chave institucional. Veja Autenticação se ainda não tem a sua.

2. Escolha o ambiente

Comece sempre por staging para validar a integração sem afetar dados reais:

https://api-staging.principia.services/api-integracao

Veja Ambientes para as URLs de staging e produção.

3. Faça sua primeira chamada (leitura)

Um bom primeiro teste é uma rota de leitura, que não altera nada. Liste parcelas originais:

curl "https://api-staging.principia.services/api-integracao/v1/parcela/originais" \
  -H "apikey: SUA_CHAVE_INSTITUCIONAL"

Se receber 200 OK com um corpo JSON, sua autenticação e conectividade estão funcionando.

4. Envie dados (escrita assíncrona)

A inclusão de parcelas e alunos é assíncrona: você envia um lote (sempre dentro de um array, mesmo que seja 1 item; mande várias parcelas de uma vez sempre que puder) e acompanha o processamento depois. Exemplo de inclusão de parcela:

curl -X POST "https://api-staging.principia.services/api-integracao/v1/parcela" \
  -H "apikey: SUA_CHAVE_INSTITUCIONAL" \
  -H "Content-Type: application/json" \
  -d '{
    "parcelas": [
      {
        "idParcela": "PARC-123",
        "alunoCpf": "81111724008",
        "alunoRa": "RA11724008",
        "responsavelFinanceiroTipoDocumento": "CPF",
        "responsavelFinanceiroDocumento": "81111724008",
        "grauCurso": "Graduação",
        "modalidadeCurso": "EAD",
        "tipoParcela": "MENSALIDADE",
        "valorBoleto": "499.90",
        "dataVencimento": "2026-09-10T00:00:00",
        "situacaoBaixa": "EM ABERTO"
      }
    ]
  }'

idParcela é o identificador da parcela no seu sistema: guarde-o, é ele que você vai usar depois para atualizar valor, cancelar ou dar baixa nessa mesma parcela (veja Fluxo de integração). A resposta traz o id do lote e a quantidade de itens recebidos, ex.: { "id": "4bcfa4e2-48ee-4ee8-b387-9ec4bbd311b9", "quantidade": 1 }.

5. Acompanhe o processamento

Com o id do lote, consulte o status:

curl "https://api-staging.principia.services/api-integracao/v1/processamento/status/4bcfa4e2-48ee-4ee8-b387-9ec4bbd311b9" \
  -H "apikey: SUA_CHAVE_INSTITUCIONAL"

Próximo passo

Entenda o caminho completo em Fluxo de integração.