Visão Geral e Convenções da API

URLs Base

Cada serviço é executado de forma independente

Serviço	URL Base
Cloud	https://cloud.mangati.com
NovoSGA	https://novosga.mangati.com
Painel	https://painel.mangati.com
Triagem	https://triagem.mangati.com
Agenda	https://agenda.mangati.com
Monitor	https://monitor.mangati.com
Avaliação	https://avaliacao.mangati.com
Notificação	https://notificacao.mangati.com

Todos os endpoints de API têm o prefixo /api.

Autenticação

Todos os endpoints requerem um token bearer no cabeçalho Authorization:

Authorization: Bearer <token>

Consulte o Guia de Autenticação para saber como obter tokens.

Formato das Requisições

Para requisições POST/PUT, envie JSON com Content-Type: application/json:

curl -X POST https://{servico}.mangati.com/api/{recurso} \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"campo": "valor"}'

Formato das Respostas

Todas as respostas são em JSON. Sempre envie Accept: application/json para receber JSON simples:

Accept: application/json

Os serviços de extensão suportam também JSON-LD (Accept: application/ld+json), que retorna o formato Hydra com metadados semânticos. Todos os exemplos desta documentação usam application/json.

Códigos de Status HTTP

Código	Significado
200	Sucesso
201	Criado
204	Sem conteúdo (exclusão bem-sucedida)
400	Requisição inválida
401	Não autorizado - token ausente ou inválido
403	Proibido - token sem o papel necessário
404	Recurso não encontrado
422	Erro de validação
500	Erro no servidor

Formato de Erros

Erros de validação (422) retornam:

{
  "type": "https://tools.ietf.org/html/rfc2616#section-10",
  "title": "Um erro ocorreu",
  "detail": "campo: Este valor não deve ser vazio.",
  "violations": [
    {
      "propertyPath": "campo",
      "message": "Este valor não deve ser vazio.",
      "code": "c1051bb4-d103-4f74-8988-acbcafc7fdc3"
    }
  ]
}

Erros dos controladores customizados do NovoSGA retornam:

{
  "error": "Mensagem de erro legível"
}

Paginação (serviços API Platform)

Endpoints de coleção com Accept: application/json retornam um array simples:

[
  { "id": "...", ... },
  { "id": "...", ... }
]

Use ?page=N para navegar entre páginas. Tamanho padrão de página: 30 itens.

Com Accept: application/ld+json a resposta inclui metadados de coleção:

{
  "@context": "/api/contexts/Appointment",
  "@id": "/api/appointments",
  "@type": "Collection",
  "totalItems": 150,
  "member": [ ... ]
}

Filtros

Endpoints API Platform suportam filtros via parâmetros de consulta:

GET /api/appointments?date=2024-06-15
GET /api/appointments?location=018e4f2b-...
GET /api/tickets?status=waiting

Os filtros disponíveis estão documentados em cada seção de referência.

IDs

Todos os recursos usam identificadores UUID (campo id). Nunca utilize IDs inteiros - eles são internos e não são expostos pela API.

Exemplo de UUID: 018e4f2a-7b3c-7000-8d2e-1a2b3c4d5e6f

Datas e Horários

• Datas: ISO 8601 - "2024-06-15"
• Horários: "HH:MM" ou datetime ISO 8601
• Timestamps: ISO 8601 com fuso horário - "2024-06-15T14:30:00+00:00"