1. Visão geral
A API SIPI está disponível em dois ambientes:
| Ambiente | Base URL |
|---|---|
| Produção | https://sipi-api.saude.pr.gov.br/ |
| Homologação | https://homolog-sipi-api.saude.pr.gov.br/ |
Cada ambiente expõe dois tipos de documentação interativa:
| Documentação | Produção | Homologação |
|---|---|---|
| ReDoc (leitura) | /api/schema/redoc/ | /api/schema/redoc/ |
| Swagger UI (teste interativo) | /api/schema/swagger-ui/ | /api/schema/swagger-ui/ |
Recomendação: sempre desenvolva e teste primeiro em Homologação. Só migre para Produção após validar o fluxo completo.
2. Como obter o token de acesso
O acesso à API é feito via token. Para solicitá-lo, envie e-mail para:
No e-mail, inclua as informações que costumam ser exigidas nesse tipo de solicitação:
- Nome completo e órgão/instituição;
- CPF ou matrícula funcional;
- Ambiente desejado (homologação e/ou produção);
- Finalidade da integração (sistema que vai consumir a API);
3. Passo a passo para consumir a API
3.1. Explorar a documentação
- Abra o Swagger UI do ambiente de homologação:
https://homolog-sipi-api.saude.pr.gov.br/api/schema/swagger-ui/ - Verifique os endpoints disponíveis, parâmetros, corpos de requisição e códigos de resposta.
- Use o ReDoc quando quiser uma leitura mais limpa e contínua da especificação.
3.2. Autenticar
O padrão mais comum em APIs com token é o envio via header Authorization.
Exemplo genérico com Token:
curl -X GET "https://homolog-sipi-api.saude.pr.gov.br/<endpoint>" \
-H "Authorization: Token SEU_TOKEN_AQUI" \
-H "Accept: application/json"3.3. Fazer a primeira chamada
- No Swagger UI, clique em Authorize e informe o token.
- Escolha um endpoint de leitura simples (ex.: consulta/ping/listagem).
- Execute e confira o retorno.
- Repita o mesmo teste via
curlou Postman para validar fora do navegador.
3.4. Tratar erros
Códigos esperados em APIs REST:
| Código | Significado | Ação |
|---|---|---|
| 200/201 | Sucesso | Processar resposta |
| 400 | Requisição inválida | Revisar parâmetros/corpo |
| 401 | Não autenticado | Verificar token |
| 403 | Sem permissão | Verificar perfil de acesso |
| 404 | Recurso não encontrado | Conferir URL/ID |
| 429 | Muitas requisições | Implementar backoff |
| 500 | Erro no servidor | Registrar e tentar novamente |
4. Boas práticas
- Nunca versione o token em repositório. Use variáveis de ambiente ou cofre de segredos.
- Separe configurações de homologação e produção (arquivos
.envdistintos). - Implemente retry com backoff exponencial para erros 5xx e 429.
- Registre logs de requisição/resposta (sem expor o token).
- Valide o certificado TLS; não desative verificação em produção.
- Monitore expiração/renovação do token.
5. Exemplo de configuração (.env)
SIPI_ENV=homologacao
SIPI_BASE_URL=https://homolog-sipi-api.saude.pr.gov.br
SIPI_TOKEN=cole_o_token_aqui
# Para produção, troque para:
# SIPI_BASE_URL=https://sipi-api.saude.pr.gov.br6. Checklist rápido
- Solicitar token por e-mail (idoso@sesa.pr.gov.br)
- Acessar Swagger UI de homologação
- Identificar endpoint e esquema de autenticação
- Testar chamada no Swagger
- Reproduzir chamada via curl/Postman
- Implementar tratamento de erros e retry
- Configurar variáveis de ambiente
- Validar em produção após aprovação