Prosit.IA
Início/GiraEstoque/API REST & Integrações
OpenAPI 3.1 • Client Credentials

Guia de Integração da API REST

Conecte o sistema da sua instituição de saúde ao GiraEstoque para sincronização automatizada de ofertas excedentes, reserva transacional com trava de estoque e recebimento de webhooks em tempo real.

Abrir Referência da APIAcessar Developer Dashboard

Client Credentials & API Key

Troca segura de clientId e clientSecret via POST /api/v1/auth por uma apiKey temporária com TTL de 2 horas.

Sync em Lote & Imagens

Endpoint batch_sync atômico para sincronizar lotes com fotos tratadas (Base64 ou URL), validação de magic bytes e cache HTTP de alta performance.

Transacional & Idempotência

Reservas com trava pessimista de estoque (lock no Postgres) e proteção contra duplicidades via header Idempotency-Key.

Webhooks Outbound

Notificações HTTP automáticas assinadas com HMAC-SHA256 sempre que ofertas forem reservadas, confirmadas ou aprovadas.

Ambiente Dedicado

Referência de Endpoints (OpenAPI 3.1)

Acesse a documentação técnica completa em página exclusiva, com console para execução de testes, schemas de parâmetros e geração de snippets em cURL, JavaScript, Python e Ruby.

Abrir Referência da APIBaixar Especificação OpenAPI YAML
Especificação RESTful

Catálogo de Endpoints da API

Navegue pelos 24 endpoints da API REST do GiraEstoque divididos por categorias funcionais. Todos os métodos suportam formatos JSON e autenticação via header X-API-KEY.

Módulo 1

Autenticação & Identidade

Troca de credenciais por tokens de acesso temporários e consulta ao tenant conectado.

Testar no Console →
POST/api/v1/authEmissão de API Key temporária via Client Credentials (TTL de 2 horas).
JSONTestar ↗
GET/api/v1/meIdentificação da instituição de saúde (tenant), ambiente ativo e expiração da chave conectada.
AutenticadoTestar ↗
Módulo 2

Gestão de Aplicações & Credenciais

Provisionamento, consulta e revogação de Client ID e Client Secret para integrações externas.

Testar no Console →
GET/api/v1/applicationsLista todas as aplicações e integrações cadastradas da instituição.
GestãoTestar ↗
POST/api/v1/applicationsCria uma nova credencial (retorna clientId e clientSecret uma única vez).
SegurançaTestar ↗
DELETE/api/v1/applications/:idRevoga a aplicação e invalida imediatamente todas as chaves ativas emitidas por ela.
RevogaçãoTestar ↗
Módulo 3

Catálogo Nacional ANVISA

Base padronizada de medicamentos, insumos de saúde, códigos de barra e fotos regulatórias.

Testar no Console →
GET/api/v1/catalogoLista paginada de produtos catalogados com código EAN e registro ANVISA.
PaginadoTestar ↗
GET/api/v1/catalogo/buscaBusca indexada por termo (nome comercial, princípio ativo ou fabricante).
BuscaTestar ↗
GET/api/v1/catalogo/:idFicha técnica detalhada com apresentação, dosagem e classificação ATC.
DetalhesTestar ↗
GET/api/v1/catalogo/:id/fotoEntrega binária direta da foto do medicamento com cabeçalhos HTTP Cache-Control.
Cache HTTPTestar ↗
Módulo 4

Ofertas & Estoque Excedente

Publicação individual, sincronização atômica em lote (batch_sync) e atualização de estoque.

Testar no Console →
POST/api/v1/ofertas/batch_syncSincronização atômica em lote enviando múltiplos lotes diretamente do ERP.
AtômicoTestar ↗
GET/api/v1/ofertasLista ofertas ativas do marketplace ou com escopo restrito às ofertas da própria instituição.
MarketplaceTestar ↗
POST/api/v1/ofertasPublicação de uma oferta individual com suporte a foto Base64 ou URL remota.
UploadTestar ↗
GET/api/v1/ofertas/:idConsulta dados completos da oferta, lote, validade e condições de transporte.
ConsultaTestar ↗
PATCH/api/v1/ofertas/:idAtualiza quantidade disponível, preço unitário ou lote de uma oferta existente.
EdiçãoTestar ↗
DELETE/api/v1/ofertas/:idEncerra a publicação da oferta e remove a disponibilidade no marketplace.
RemoçãoTestar ↗
GET/api/v1/ofertas/:id/fotoDownload binário da imagem real do produto cadastrada pela farmácia ou serviço de saúde.
BinárioTestar ↗
Módulo 5

Reservas & Baixa de Estoque

Operações transacionais ACID com trava pessimista de saldo (lock no Postgres) e aprovação de baixa.

Testar no Console →
POST/api/v1/ofertas/:id/reservarCria uma reserva com trava concorrente imediata, evitando reservas duplicadas.
Lock PessimistaTestar ↗
GET/api/v1/reservasConsulta as reservas ativas da instituição em andamento.
ListagemTestar ↗
GET/api/v1/reservas/:idDetalhes da reserva, saldo retido e prazo limite para confirmação.
DetalhesTestar ↗
POST/api/v1/reservas/:id/confirmarConfirmação da reserva pela instituição adquirente para seguir para aprovação.
ConfirmaçãoTestar ↗
POST/api/v1/reservas/:id/cancelarCancela a reserva e devolve imediatamente a quantidade ao saldo disponível da oferta.
RollbackTestar ↗
POST/api/v1/aprovacoes/:id/aprovarAprova a transferência/doação e realiza a baixa definitiva de estoque no sistema.
Baixa ACIDTestar ↗
POST/api/v1/aprovacoes/:id/rejeitarRejeita o pedido de reserva com justificativa e libera o insumo para outros interessados.
RejeiçãoTestar ↗
Módulo 6

Transações & Auditoria

Registros imutáveis de transações concluídas para conformidade regulatória, sanitária e fiscal.

Testar no Console →
GET/api/v1/transacoesHistórico completo de transações finalizadas (trocas, doações e vendas).
AuditoriaTestar ↗
GET/api/v1/transacoes/:idComprovante de transação com carimbo de data/hora, lotes envolvidos e dados do recebedor.
ComprovanteTestar ↗
Módulo 7

Webhooks Outbound (HMAC-SHA256)

Notificações automáticas em tempo real para sincronização com o ERP da sua instituição de saúde.

Testar no Console →
GET/api/v1/webhooksLista todos os endpoints de webhook cadastrados pela instituição.
ListagemTestar ↗
POST/api/v1/webhooksCadastra uma nova URL receptora e emite o segredo HMAC para validação criptográfica.
HMAC SecretoTestar ↗
GET/api/v1/webhooks/:idConsulta dados do endpoint, status de ativação e eventos inscritos.
StatusTestar ↗
DELETE/api/v1/webhooks/:idDesativa o webhook e suspende os disparos de notificação HTTP.
DesativaçãoTestar ↗
GET/api/v1/webhooks/:id/deliveriesHistórico dos últimos 50 disparos com status HTTP, payload e latência de entrega.
Logs & LatênciaTestar ↗

Exemplos de Integração (cURL)

Comandos prontos para teste rápido:

1. Autenticação (Client Credentials)
curl -X POST http://localhost:3000/api/v1/auth \
  -H "Content-Type: application/json" \
  -d '{"clientId": "SEU_CLIENT_ID", "clientSecret": "SEU_CLIENT_SECRET"}'
2. Sincronização em Lote de Ofertas (batch_sync)
curl -X POST http://localhost:3000/api/v1/ofertas/batch_sync \
  -H "X-API-KEY: 8f92a10b-42d1-4c93-ae41-2a076d1e49b8" \
  -H "Content-Type: application/json" \
  -d '{
    "ofertas": [
      {
        "produto_id": 1,
        "lote": "LOTE-2026-X",
        "quantidade_disponivel": 200,
        "data_validade": "2027-01-31",
        "preco_unitario": 12.50
      }
    ]
  }'