{ "openapi": "3.0.3", "info": { "title": "API do DestinoLab Paraty", "version": "1.2.0", "description": "Ponte entre as cinco soluções do DestinoLab Paraty e o banco central do destino. Referência completa em https://docs.destinolabparaty.com.br/" }, "servers": [ { "url": "https://api.destinolabparaty.com.br", "description": "API" }, { "url": "https://auth.destinolabparaty.com.br", "description": "Identidade (OAuth)" } ], "tags": [ { "name": "Autenticação", "description": "Integração máquina a máquina usa OAuth 2.1 client_credentials: troque o client_id e o client_secret por um access_token (JWT RS256, 15 minutos) e mande-o em Authorization: Bearer. Não há refresh token nesse fluxo: peça outro token quando o atual vencer. O segredo nunca vai em URL nem em corpo JSON." }, { "name": "Atrativos (POIs)", "description": "O catálogo canônico: um código (PTY-POI-0001) e um UUID de QR Code por atrativo, iguais para as cinco soluções. Quem cria e publica é a curadoria (a Prefeitura); as soluções leem o que está publicado." }, { "name": "Check-ins", "description": "Qualquer das cinco soluções registra que alguém esteve num atrativo. O atrativo vem pelo código ou pelo UUID lido no QR Code. O check-in pode ser anônimo (só conta) ou levar o sub do visitante que fez login na solução. Nome, e-mail, telefone ou documento de visitante nunca entram aqui: campo desconhecido é recusado com 422." }, { "name": "Resíduos: pontos de coleta, pesagens e destinação", "description": "Quem opera a coleta cadastra os pontos que mantém dentro de cada atrativo (quantos forem precisos) e depois informa quanto saiu de cada ponto, por material. Peso sempre em gramas, inteiro: 12,4 kg é 12400. Cada ponto só é alterado, e só recebe pesagem, de quem o cadastrou. As outras soluções e o portal leem." }, { "name": "Conteúdo das soluções e roteiros", "description": "A ficha do atrativo é da curadoria. Cada solução acrescenta a sua camada: a narrativa, a interpretação ambiental, a memória, a orientação de conduta, e os roteiros que ligam atrativos. O portal e as outras soluções leem e mostram com o nome de quem assinou. Só quem publicou altera ou retira. O texto é puro: quem exibe faz o escape." }, { "name": "Ofertas, grade de saídas e reservas", "description": "A solução que vende publica a oferta de um operador homologado e mantém a grade de saídas. As outras leem para mostrar disponibilidade, e qualquer solução com o escopo informa a reserva que vendeu: o centro controla as vagas. Dinheiro sempre em centavos, inteiro. Nenhum nome, e-mail ou telefone do comprador entra aqui: quando a pessoa é conhecida, vem só o sub." }, { "name": "Registro de saída e ocorrências", "description": "Quem ordena os passeios informa cada saída ao partir e o retorno ao voltar. A gestão consulta o que ainda está fora: numa emergência, sabe quem saiu, em que embarcação e com quantas pessoas. Só contagem: nenhum nome de passageiro ou de condutor." }, { "name": "Passaporte", "description": "Carimbos por atrativo visitado, emitidos pelas cinco soluções na conta única do visitante. A solução fala em sub; o centro resolve a pessoa. Exige que o visitante tenha autorizado a solução a carimbar." }, { "name": "Operadores, equipamentos e selos", "description": "Prestadores de serviço turístico e suas embarcações e veículos. As soluções veem só os homologados. O documento (CPF ou CNPJ) é cifrado e só volta mascarado." }, { "name": "Painel (dashboards)", "description": "O que as cinco soluções mandaram para o centro, somado. É de onde o portal e os dashboards leem. Só agregados: nenhuma informação de pessoa. Período padrão: os últimos 30 dias; máximo de 366 dias." }, { "name": "Agenda, busca e conteúdo", "description": "O que o portal mostra além dos atrativos: a agenda da cidade, a busca unificada, as páginas editoriais e os subdomínios das soluções." }, { "name": "Conta do visitante (token de login)", "description": "Estas rotas só aceitam o token que o visitante obtém ao fazer login (Authorization Code + PKCE em auth.destinolabparaty.com.br/oauth/autorizar). Token de máquina recebe 403. Há uma única base de visitantes: cada solução recebe um sub diferente para a mesma pessoa e nunca coleta senha." }, { "name": "Saúde", "description": "Para monitoramento. Sem autenticação." } ], "paths": { "/oauth/token": { "post": { "tags": [ "Autenticação" ], "summary": "Obter token (client_credentials)", "description": "Autentique o client por HTTP Basic (client_id:client_secret). O token sai com todos os escopos do client; para pedir menos, mande scope com os escopos separados por espaço. Até 60 chamadas por minuto por IP; 30 falhas por minuto bloqueiam o client por até 1 minuto.", "operationId": "post_oauth_token", "servers": [ { "url": "https://auth.destinolabparaty.com.br" } ], "security": [ { "clientBasic": [] } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "grant_type": { "type": "string", "example": "client_credentials" } } } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6ImRscC0yMDI2MTEwNi1iNWI2NmJiZiJ9…", "token_type": "Bearer", "expires_in": 900, "scope": "catalogo:ler checkins:escrever checkins:ler operadores:ler passaporte:escrever residuos:ler" } } } }, "401": { "description": "invalid_client: client_id ou client_secret errado.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" } } } }, "429": { "description": "Muitas tentativas; veja Retry-After.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" } } } } } } }, "/v1/cliente": { "get": { "tags": [ "Autenticação" ], "summary": "Quem sou eu (teste de conectividade)", "description": "Devolve o client, o parceiro e os escopos do token. É a primeira chamada a fazer depois de receber a credencial.", "operationId": "get_v1_cliente", "servers": [ { "url": "https://api.destinolabparaty.com.br" } ], "security": [ { "bearer": [] } ], "x-escopo": "qualquer token", "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "client_id": "fuba-maquina", "parceiro": "fuba", "escopos": [ "catalogo:ler", "checkins:escrever", "checkins:ler", "operadores:ler", "passaporte:escrever", "residuos:ler" ], "token_expira_em": "2026-11-10T14:02:11-03:00" } } } } } } }, "/oauth/introspeccao": { "post": { "tags": [ "Autenticação" ], "summary": "Conferir um token", "description": "RFC 7662. Cada client só enxerga os próprios tokens; token de outro client responde active: false.", "operationId": "post_oauth_introspeccao", "servers": [ { "url": "https://auth.destinolabparaty.com.br" } ], "security": [ { "clientBasic": [] } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "token": { "type": "string", "example": "eyJhbGciOiJSUzI1NiJ9…" } } } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "active": true, "client_id": "fuba-maquina", "scope": "catalogo:ler checkins:escrever", "exp": 1794330131, "token_type": "Bearer" } } } } } } }, "/oauth/revogar": { "post": { "tags": [ "Autenticação" ], "summary": "Revogar um token", "description": "RFC 7009. A chamada seguinte com o token revogado já responde 401. Responde 200 mesmo se o token não existir.", "operationId": "post_oauth_revogar", "servers": [ { "url": "https://auth.destinolabparaty.com.br" } ], "security": [ { "clientBasic": [] } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "token": { "type": "string", "example": "eyJhbGciOiJSUzI1NiJ9…" } } } } } }, "responses": { "200": { "description": "Sucesso" } } } }, "/.well-known/openid-configuration": { "get": { "tags": [ "Autenticação" ], "summary": "Descoberta OIDC", "description": "Endereços e capacidades do provedor de identidade.", "operationId": "get_well_known_openid_configuration", "servers": [ { "url": "https://auth.destinolabparaty.com.br" } ], "security": [], "responses": { "200": { "description": "Sucesso" } } } }, "/.well-known/jwks.json": { "get": { "tags": [ "Autenticação" ], "summary": "Chaves públicas (JWKS)", "description": "Para quem quiser validar a assinatura do JWT por conta própria. A chave roda a cada 90 dias; a anterior segue publicada por 24 h.", "operationId": "get_well_known_jwks_json", "servers": [ { "url": "https://auth.destinolabparaty.com.br" } ], "security": [], "responses": { "200": { "description": "Sucesso" } } } }, "/v1/pois": { "get": { "tags": [ "Atrativos (POIs)" ], "summary": "Buscar e listar atrativos", "description": "Só os publicados (a curadoria vê todos). Cada item traz o qr_uuid. Paginação por cursor: repita a chamada com depois = pagina.proximo enquanto tem_mais for verdadeiro.", "operationId": "get_v1_pois", "servers": [ { "url": "https://api.destinolabparaty.com.br" } ], "security": [ { "bearer": [] } ], "x-escopo": "catalogo:ler", "parameters": [ { "name": "busca", "in": "query", "required": false, "description": "Texto no nome ou no nome traduzido (2 a 100 caracteres)", "schema": { "type": "string" } }, { "name": "qr_uuid", "in": "query", "required": false, "description": "UUID lido no QR Code do atrativo: devolve o atrativo dono dele", "schema": { "type": "string" } }, { "name": "categoria", "in": "query", "required": false, "description": "Código da categoria (inclui as filhas), como praia ou historico", "schema": { "type": "string" } }, { "name": "tipo", "in": "query", "required": false, "description": "atrativo, equipamento, servico, area, ponto_embarque ou trilha", "schema": { "type": "string" } }, { "name": "proximo_de", "in": "query", "required": false, "description": "lat,lng; exige raio_m e acrescenta distancia_m em cada item", "schema": { "type": "string" } }, { "name": "raio_m", "in": "query", "required": false, "description": "Raio em metros, de 1 a 200000", "schema": { "type": "string" } }, { "name": "atualizado_apos", "in": "query", "required": false, "description": "ISO 8601 com fuso: só o que mudou depois (sincronização incremental)", "schema": { "type": "string" } }, { "name": "idioma", "in": "query", "required": false, "description": "pt-BR, en-US, es-ES ou fr-FR: idioma de nome e resumo, com fallback para pt-BR", "schema": { "type": "string" } }, { "name": "slug", "in": "query", "required": false, "description": "Filtra pelo slug", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Só a curadoria: rascunho, em_revisao, publicado, suspenso, arquivado", "schema": { "type": "string" } }, { "name": "limite", "in": "query", "required": false, "description": "1 a 200 (padrão 50)", "schema": { "type": "string" } }, { "name": "depois", "in": "query", "required": false, "description": "Cursor da página anterior", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "dados": [ { "codigo": "PTY-POI-0001", "tipo": "atrativo", "nome": "Centro Histórico de Paraty", "slug": "centro-historico-de-paraty", "status": "publicado", "qr_uuid": "0f8fad5b-d9cb-469f-a165-70867728950e", "localizacao": { "latitude": -23.21802, "longitude": -44.71305 }, "categorias": [ "historico", "cultura" ], "resumo": "Conjunto de casarões coloniais e ruas de pedra sem carros entre o rio Perequê-Açu e a baía.", "idioma": "pt-BR", "imagem_principal": { "url": "https://img.destinolabparaty.com.br/attractions/historic-center/exemplo.jpg", "texto_alt": "Rua de pedras do Centro Histórico de Paraty, com casarões coloniais caiados." }, "atualizado_em": "2026-11-06T00:21:02-03:00" } ], "pagina": { "limite": 20, "proximo": "eyJjIjoiUFRZLVBPSS0wMDAxIn0", "tem_mais": true } } } } } } }, "post": { "tags": [ "Atrativos (POIs)" ], "summary": "Criar atrativo (curadoria)", "description": "Só a Prefeitura. O código e o qr_uuid são gerados aqui e não mudam mais. Publicar exige nome, coordenadas, ao menos uma categoria e i18n.pt-BR.resumo.", "operationId": "post_v1_pois", "servers": [ { "url": "https://api.destinolabparaty.com.br" } ], "security": [ { "bearer": [] } ], "x-escopo": "catalogo:escrever", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "1 a 120 caracteres: letras, números e . _ : ~ -", "schema": { "type": "string", "maxLength": 120 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "nome": "Praça da Matriz", "tipo": "atrativo", "status": "rascunho", "localizacao": { "latitude": -23.2178, "longitude": -44.7131 }, "categorias": [ "historico" ], "i18n": { "pt-BR": { "resumo": "Praça central do Centro Histórico, diante da Igreja Matriz." } } } } } }, "responses": { "201": { "description": "Sucesso" }, "403": { "description": "O client não é da curadoria.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" } } } } } } }, "/v1/pois/{codigo}": { "get": { "tags": [ "Atrativos (POIs)" ], "summary": "Detalhe do atrativo", "description": "Traz o qr_uuid, os textos nos quatro idiomas e a geometria. Devolve ETag; com If-None-Match igual responde 304.", "operationId": "get_v1_pois_codigo", "servers": [ { "url": "https://api.destinolabparaty.com.br" } ], "security": [ { "bearer": [] } ], "x-escopo": "catalogo:ler", "parameters": [ { "name": "codigo", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "incluir", "in": "query", "required": false, "description": "Seções extras, separadas por vírgula: midias, horarios, tarifas, operadores, acessibilidade", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "codigo": "PTY-POI-0003", "tipo": "atrativo", "nome": "Praia da Lula", "slug": "praia-da-lula", "status": "publicado", "versao": 5, "qr_uuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "localizacao": { "logradouro": null, "numero": null, "complemento": null, "bairro": null, "cep": null, "municipio_ibge": "3303807", "latitude": -23.19674, "longitude": -44.62959, "como_chegar_resumo": null, "meio_acesso": [ "nautico" ] }, "contato": { "telefone": null, "email": null, "site": null }, "gestao": { "orgao_gestor": null, "unidade_conservacao": null, "nivel_tombamento": "nenhum", "processo_tombamento": null }, "capacidade": { "dia": null, "saida": null, "fonte": null, "definida_em": null }, "visitacao": { "exige_agendamento": false, "exige_guia": false, "exige_taxa": false, "regra_mare": null, "vinculo_comunitario": null, "protocolo_visitacao": null, "restricoes": null }, "categorias": [ { "codigo": "praia", "nome": "Praias e ilhas", "principal": true } ], "i18n": { "pt-BR": { "resumo": "Praia de águas claras e calmas diante das ilhas Catimbau e Comprida.", "descricao": "…" }, "en-US": { "nome": "Lula Beach", "resumo": "Clear, calm water facing the Catimbau and Comprida islands." } }, "geometria": { "type": "Point", "coordinates": [ -44.62959, -23.19674 ] }, "curadoria": { "curador": "prefeitura", "homologado_por": "prefeitura-maquina", "homologado_em": "2026-11-05T23:50:38-03:00" }, "publicado_em": "2026-11-05T23:50:38-03:00", "criado_em": "2026-11-05T23:43:55-03:00", "atualizado_em": "2026-11-06T00:21:05-03:00", "midias": [ { "tipo": "imagem", "url": "https://img.destinolabparaty.com.br/attractions/lula-beach/exemplo.jpg", "url_thumb": "https://img.destinolabparaty.com.br/attractions/lula-beach/exemplo-w480.jpg", "largura": 1024, "altura": 682, "texto_alt": "Casa de veraneio colonial entre coqueiros e mata, à beira da água clara da Praia da Lula.", "legenda": "Praia da Lula", "credito": "Diego Torres Silvestre, CC BY 2.0 (Wikimedia Commons)", "licenca": "CC-BY-2.0", "principal": true, "ordem": 0, "contribuicao_de": "prefeitura" } ] } } } }, "404": { "description": "Código inexistente, ou atrativo ainda não publicado.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" } } } } } }, "patch": { "tags": [ "Atrativos (POIs)" ], "summary": "Alterar atrativo", "description": "Exige If-Match com o ETag lido no GET (428 sem o cabeçalho; 412 se outro alterou antes). Ausente = não mexer; null = limpar. O qr_uuid e o código não são editáveis.", "operationId": "patch_v1_pois_codigo", "servers": [ { "url": "https://api.destinolabparaty.com.br" } ], "security": [ { "bearer": [] } ], "x-escopo": "catalogo:escrever", "parameters": [ { "name": "codigo", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" }, "example": "W/\"5\"" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "contato": { "site": "https://exemplo.org" }, "visitacao": { "exige_guia": true } } } } }, "responses": { "200": { "description": "Sucesso" } } } }, "/v1/pois/{codigo}/midias": { "post": { "tags": [ "Atrativos (POIs)" ], "summary": "Anexar imagem ao atrativo", "description": "multipart/form-data com o campo arquivo (JPEG, PNG ou WebP, até 12 MB) e os demais campos como texto; ou JSON com url do domínio de mídia. texto_alt é obrigatório: a API recusa imagem sem descrição.", "operationId": "post_v1_pois_codigo_midias", "servers": [ { "url": "https://api.destinolabparaty.com.br" } ], "security": [ { "bearer": [] } ], "x-escopo": "catalogo:escrever", "parameters": [ { "name": "codigo", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "1 a 120 caracteres: letras, números e . _ : ~ -", "schema": { "type": "string", "maxLength": 120 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "url": "https://img.destinolabparaty.com.br/attractions/lula-beach/exemplo.jpg", "texto_alt": "Praia de areia clara com uma casa de veraneio entre coqueiros.", "credito": "Nome do autor, CC BY 2.0", "licenca": "CC BY 2.0", "legenda": "A Praia da Lula vista do mar", "principal": false, "ordem": 1 } } } }, "responses": { "201": { "description": "Sucesso" } } } }, "/v1/categorias": { "get": { "tags": [ "Atrativos (POIs)" ], "summary": "Categorias", "description": "Pública. Cache de 1 hora.", "operationId": "get_v1_categorias", "servers": [ { "url": "https://api.destinolabparaty.com.br" } ], "security": [], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "dados": [ { "codigo": "nautico", "nome": "Passeios náuticos", "pai": null, "icone": null, "cor": null } ] } } } } } } }, "/v1/catalogo/aberto.json": { "get": { "tags": [ "Atrativos (POIs)" ], "summary": "Catálogo aberto (JSON)", "description": "Pública. Todos os atrativos publicados num arquivo só, em formato aberto. Cache de 5 minutos.", "operationId": "get_v1_catalogo_aberto_json", "servers": [ { "url": "https://api.destinolabparaty.com.br" } ], "security": [], "responses": { "200": { "description": "Sucesso" } } } }, "/v1/catalogo/aberto.geojson": { "get": { "tags": [ "Atrativos (POIs)" ], "summary": "Catálogo aberto (GeoJSON)", "description": "Pública. FeatureCollection (RFC 7946) que abre direto no QGIS.", "operationId": "get_v1_catalogo_aberto_geojson", "servers": [ { "url": "https://api.destinolabparaty.com.br" } ], "security": [], "responses": { "200": { "description": "Sucesso" } } } }, "/v1/checkins": { "post": { "tags": [ "Check-ins" ], "summary": "Registrar check-in", "description": "Responde 201 com criado: true. Se a referencia_externa já foi usada pela solução, responde 200 com o check-in que já existia e criado: false. O check-in não carimba o passaporte: isso é POST /v1/passaporte/carimbos.", "operationId": "post_v1_checkins", "servers": [ { "url": "https://api.destinolabparaty.com.br" } ], "security": [ { "bearer": [] } ], "x-escopo": "checkins:escrever", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "1 a 120 caracteres: letras, números e . _ : ~ -", "schema": { "type": "string", "maxLength": 120 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "poi": { "description": "Código do atrativo. Informe poi ou qr_uuid, um dos dois" }, "qr_uuid": { "description": "UUID lido no QR Code do atrativo" }, "origem": { "description": "qr (padrão), geo, reserva ou manual" }, "pessoas": { "description": "Tamanho do grupo, de 1 a 500 (padrão 1)" }, "ocorrido_em": { "description": "ISO 8601 com fuso; padrão: agora. Não pode estar no futuro" }, "sub": { "description": "Opcional. O sub pairwise que a sua solução recebeu no login do visitante" }, "referencia_externa": { "description": "Opcional. O id do check-in no seu sistema (até 80 caracteres); impede duplicata" } } }, "example": { "qr_uuid": "0f8fad5b-d9cb-469f-a165-70867728950e", "origem": "qr", "pessoas": 2, "ocorrido_em": "2026-12-27T10:30:00-03:00", "referencia_externa": "app-778" } } } }, "responses": { "200": { "description": "Já existia (repetição)", "content": { "application/json": { "schema": { "type": "object" }, "example": { "criado": true, "uuid": "b1a7c1de-3f0a-4c55-9d0e-6a1f2c3d4e5f", "poi": "PTY-POI-0001", "solucao": "fuba", "origem": "qr", "pessoas": 2, "identificado": false, "ocorrido_em": "2026-12-27T10:30:00-03:00", "referencia_externa": "app-778", "registrado_em": "2026-12-27T10:30:04-03:00" } } } }, "201": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "criado": true, "uuid": "b1a7c1de-3f0a-4c55-9d0e-6a1f2c3d4e5f", "poi": "PTY-POI-0001", "solucao": "fuba", "origem": "qr", "pessoas": 2, "identificado": false, "ocorrido_em": "2026-12-27T10:30:00-03:00", "referencia_externa": "app-778", "registrado_em": "2026-12-27T10:30:04-03:00" } } } }, "403": { "description": "Sem o escopo, ou o visitante do sub revogou o consentimento com a solução.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" } } } }, "404": { "description": "Nenhum visitante com este sub no setor da solução.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" } } } }, "422": { "description": "Atrativo inexistente ou não publicado, data no futuro ou sem fuso, campo desconhecido.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" } } } } } }, "get": { "tags": [ "Check-ins" ], "summary": "Listar check-ins", "description": "Cada solução vê só os seus; a curadoria vê os de todas. Do mais recente para o mais antigo.", "operationId": "get_v1_checkins", "servers": [ { "url": "https://api.destinolabparaty.com.br" } ], "security": [ { "bearer": [] } ], "x-escopo": "checkins:ler", "parameters": [ { "name": "poi", "in": "query", "required": false, "description": "Código do atrativo", "schema": { "type": "string" } }, { "name": "de", "in": "query", "required": false, "description": "Dia inicial, AAAA-MM-DD (fuso de Paraty)", "schema": { "type": "string" } }, { "name": "ate", "in": "query", "required": false, "description": "Dia final, AAAA-MM-DD, incluído", "schema": { "type": "string" } }, { "name": "limite", "in": "query", "required": false, "description": "1 a 200 (padrão 50)", "schema": { "type": "string" } }, { "name": "depois", "in": "query", "required": false, "description": "Cursor da página anterior", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "dados": [ { "uuid": "b1a7c1de-3f0a-4c55-9d0e-6a1f2c3d4e5f", "poi": "PTY-POI-0001", "solucao": "fuba", "origem": "qr", "pessoas": 2, "identificado": false, "ocorrido_em": "2026-12-27T10:30:00-03:00", "referencia_externa": "app-778", "registrado_em": "2026-12-27T10:30:04-03:00" } ], "pagina": { "limite": 50, "proximo": null, "tem_mais": false } } } } } } } }, "/v1/pois/{codigo}/pontos-de-coleta": { "post": { "tags": [ "Resíduos: pontos de coleta, pesagens e destinação" ], "summary": "Cadastrar ponto de coleta num atrativo", "description": "O código do ponto (PTY-COL-0001) é gerado aqui. Repetir a mesma referencia_externa devolve 200 com o ponto que já existe, sem criar outro.", "operationId": "post_v1_pois_codigo_pontos_de_coleta", "servers": [ { "url": "https://api.destinolabparaty.com.br" } ], "security": [ { "bearer": [] } ], "x-escopo": "residuos:escrever", "parameters": [ { "name": "codigo", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "1 a 120 caracteres: letras, números e . _ : ~ -", "schema": { "type": "string", "maxLength": 120 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "nome": { "description": "Obrigatório, 2 a 160 caracteres" }, "descricao": { "description": "Até 500 caracteres" }, "tipo": { "description": "lixeira (padrão), ecoponto, conteiner, entrega_voluntaria ou outro" }, "materiais": { "description": "Lista: reciclavel, papel, plastico, vidro, metal, organico, rejeito, oleo, eletronico" }, "localizacao": { "description": "latitude e longitude do ponto" }, "capacidade_litros": { "description": "Inteiro" }, "referencia_externa": { "description": "O id do ponto no seu sistema; impede duplicata" }, "status": { "description": "ativo (padrão) ou inativo" }, "instalado_em": { "description": "AAAA-MM-DD" } } }, "example": { "nome": "Lixeira da entrada da praia", "descricao": "Ao lado do quiosque, na chegada dos barcos.", "tipo": "lixeira", "materiais": [ "plastico", "metal" ], "localizacao": { "latitude": -23.19671, "longitude": -44.62951 }, "capacidade_litros": 240, "referencia_externa": "RS-PT-01", "instalado_em": "2026-10-20" } } } }, "responses": { "200": { "description": "Já existia (repetição)", "content": { "application/json": { "schema": { "type": "object" }, "example": { "criado": true, "coletas": 0, "total_coletado_gramas": 0, "ultima_coleta_em": null, "codigo": "PTY-COL-0001", "poi": "PTY-POI-0003", "operado_por": "reciclo", "nome": "Lixeira da entrada da praia", "descricao": "Ao lado do quiosque, na chegada dos barcos.", "tipo": "lixeira", "materiais": [ "plastico", "metal" ], "localizacao": { "latitude": -23.19671, "longitude": -44.62951 }, "capacidade_litros": 240, "referencia_externa": "RS-PT-01", "status": "ativo", "instalado_em": "2026-10-20", "criado_em": "2026-10-20T09:12:44-03:00", "atualizado_em": "2026-10-20T09:12:44-03:00" } } } }, "201": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "criado": true, "coletas": 0, "total_coletado_gramas": 0, "ultima_coleta_em": null, "codigo": "PTY-COL-0001", "poi": "PTY-POI-0003", "operado_por": "reciclo", "nome": "Lixeira da entrada da praia", "descricao": "Ao lado do quiosque, na chegada dos barcos.", "tipo": "lixeira", "materiais": [ "plastico", "metal" ], "localizacao": { "latitude": -23.19671, "longitude": -44.62951 }, "capacidade_litros": 240, "referencia_externa": "RS-PT-01", "status": "ativo", "instalado_em": "2026-10-20", "criado_em": "2026-10-20T09:12:44-03:00", "atualizado_em": "2026-10-20T09:12:44-03:00" } } } }, "404": { "description": "Atrativo inexistente ou não publicado.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" } } } } } }, "get": { "tags": [ "Resíduos: pontos de coleta, pesagens e destinação" ], "summary": "Pontos de coleta de um atrativo", "description": "Cada ponto vem com o total já coletado nele e a data da última coleta.", "operationId": "get_v1_pois_codigo_pontos_de_coleta", "servers": [ { "url": "https://api.destinolabparaty.com.br" } ], "security": [ { "bearer": [] } ], "x-escopo": "residuos:ler", "parameters": [ { "name": "codigo", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "ativo ou inativo", "schema": { "type": "string" } }, { "name": "limite", "in": "query", "required": false, "description": "1 a 200", "schema": { "type": "string" } }, { "name": "depois", "in": "query", "required": false, "description": "Cursor da página anterior", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "dados": [ { "codigo": "PTY-COL-0001", "poi": "PTY-POI-0003", "operado_por": "reciclo", "nome": "Lixeira da entrada da praia", "descricao": "Ao lado do quiosque, na chegada dos barcos.", "tipo": "lixeira", "materiais": [ "plastico", "metal" ], "localizacao": { "latitude": -23.19671, "longitude": -44.62951 }, "capacidade_litros": 240, "referencia_externa": "RS-PT-01", "status": "ativo", "instalado_em": "2026-10-20", "coletas": 2, "total_coletado_gramas": 15500, "ultima_coleta_em": "2026-11-02T08:05:00-03:00", "criado_em": "2026-10-20T09:12:44-03:00", "atualizado_em": "2026-10-20T09:12:44-03:00" } ], "pagina": { "limite": 50, "proximo": null, "tem_mais": false } } } } } } } }, "/v1/pontos-de-coleta": { "get": { "tags": [ "Resíduos: pontos de coleta, pesagens e destinação" ], "summary": "Todos os pontos de coleta", "description": "A mesma lista, sem partir de um atrativo.", "operationId": "get_v1_pontos_de_coleta", "servers": [ { "url": "https://api.destinolabparaty.com.br" } ], "security": [ { "bearer": [] } ], "x-escopo": "residuos:ler", "parameters": [ { "name": "poi", "in": "query", "required": false, "description": "Código do atrativo", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "ativo ou inativo", "schema": { "type": "string" } }, { "name": "limite", "in": "query", "required": false, "description": "1 a 200", "schema": { "type": "string" } }, { "name": "depois", "in": "query", "required": false, "description": "Cursor da página anterior", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "dados": [ { "codigo": "PTY-COL-0001", "poi": "PTY-POI-0003", "operado_por": "reciclo", "nome": "Lixeira da entrada da praia", "descricao": "Ao lado do quiosque, na chegada dos barcos.", "tipo": "lixeira", "materiais": [ "plastico", "metal" ], "localizacao": { "latitude": -23.19671, "longitude": -44.62951 }, "capacidade_litros": 240, "referencia_externa": "RS-PT-01", "status": "ativo", "instalado_em": "2026-10-20", "coletas": 2, "total_coletado_gramas": 15500, "ultima_coleta_em": "2026-11-02T08:05:00-03:00", "criado_em": "2026-10-20T09:12:44-03:00", "atualizado_em": "2026-10-20T09:12:44-03:00" } ], "pagina": { "limite": 50, "proximo": null, "tem_mais": false } } } } } } } }, "/v1/pontos-de-coleta/{codigo}": { "get": { "tags": [ "Resíduos: pontos de coleta, pesagens e destinação" ], "summary": "Detalhe do ponto de coleta", "description": "Com os totais do ponto.", "operationId": "get_v1_pontos_de_coleta_codigo", "servers": [ { "url": "https://api.destinolabparaty.com.br" } ], "security": [ { "bearer": [] } ], "x-escopo": "residuos:ler", "parameters": [ { "name": "codigo", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "codigo": "PTY-COL-0001", "poi": "PTY-POI-0003", "operado_por": "reciclo", "nome": "Lixeira da entrada da praia", "descricao": "Ao lado do quiosque, na chegada dos barcos.", "tipo": "lixeira", "materiais": [ "plastico", "metal" ], "localizacao": { "latitude": -23.19671, "longitude": -44.62951 }, "capacidade_litros": 240, "referencia_externa": "RS-PT-01", "status": "ativo", "instalado_em": "2026-10-20", "coletas": 2, "total_coletado_gramas": 15500, "ultima_coleta_em": "2026-11-02T08:05:00-03:00", "criado_em": "2026-10-20T09:12:44-03:00", "atualizado_em": "2026-10-20T09:12:44-03:00" } } } } } }, "patch": { "tags": [ "Resíduos: pontos de coleta, pesagens e destinação" ], "summary": "Alterar ponto de coleta", "description": "Mesmos campos do cadastro, todos opcionais. Para desativar um ponto, mande status: inativo (o histórico de coletas permanece). Só quem cadastrou o ponto altera.", "operationId": "patch_v1_pontos_de_coleta_codigo", "servers": [ { "url": "https://api.destinolabparaty.com.br" } ], "security": [ { "bearer": [] } ], "x-escopo": "residuos:escrever", "parameters": [ { "name": "codigo", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "inativo" } } } }, "responses": { "200": { "description": "Sucesso" }, "403": { "description": "O ponto é operado por outra organização.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" } } } } } } }, "/v1/pontos-de-coleta/{codigo}/coletas": { "post": { "tags": [ "Resíduos: pontos de coleta, pesagens e destinação" ], "summary": "Registrar quanto foi coletado", "description": "Uma chamada por material pesado. Repetir a mesma referencia_externa devolve 200 com a coleta que já existe.", "operationId": "post_v1_pontos_de_coleta_codigo_coletas", "servers": [ { "url": "https://api.destinolabparaty.com.br" } ], "security": [ { "bearer": [] } ], "x-escopo": "residuos:escrever", "parameters": [ { "name": "codigo", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "1 a 120 caracteres: letras, números e . _ : ~ -", "schema": { "type": "string", "maxLength": 120 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "material": { "description": "Obrigatório: reciclavel, papel, plastico, vidro, metal, organico, rejeito, oleo ou eletronico" }, "peso_gramas": { "description": "Obrigatório. Inteiro, em gramas (1 a 50000000). Número com vírgula é recusado" }, "coletado_em": { "description": "Obrigatório. ISO 8601 com fuso; não pode estar no futuro" }, "observacao": { "description": "Até 255 caracteres" }, "referencia_externa": { "description": "O id da pesagem no seu sistema; impede duplicata" } } }, "example": { "material": "plastico", "peso_gramas": 12400, "coletado_em": "2026-11-02T08:00:00-03:00", "referencia_externa": "pes-2026-11-02-01" } } } }, "responses": { "200": { "description": "Já existia (repetição)", "content": { "application/json": { "schema": { "type": "object" }, "example": { "criado": true, "uuid": "c2d3e4f5-0a1b-4c2d-8e3f-4a5b6c7d8e9f", "ponto_de_coleta": "PTY-COL-0001", "poi": "PTY-POI-0003", "material": "plastico", "peso_gramas": 12400, "coletado_em": "2026-11-02T08:00:00-03:00", "observacao": null, "referencia_externa": "pes-2026-11-02-01", "registrado_em": "2026-11-02T08:01:10-03:00" } } } }, "201": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "criado": true, "uuid": "c2d3e4f5-0a1b-4c2d-8e3f-4a5b6c7d8e9f", "ponto_de_coleta": "PTY-COL-0001", "poi": "PTY-POI-0003", "material": "plastico", "peso_gramas": 12400, "coletado_em": "2026-11-02T08:00:00-03:00", "observacao": null, "referencia_externa": "pes-2026-11-02-01", "registrado_em": "2026-11-02T08:01:10-03:00" } } } } } }, "get": { "tags": [ "Resíduos: pontos de coleta, pesagens e destinação" ], "summary": "Coletas de um ponto", "description": "Da mais recente para a mais antiga.", "operationId": "get_v1_pontos_de_coleta_codigo_coletas", "servers": [ { "url": "https://api.destinolabparaty.com.br" } ], "security": [ { "bearer": [] } ], "x-escopo": "residuos:ler", "parameters": [ { "name": "codigo", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "de", "in": "query", "required": false, "description": "Dia inicial, AAAA-MM-DD", "schema": { "type": "string" } }, { "name": "ate", "in": "query", "required": false, "description": "Dia final, AAAA-MM-DD, incluído", "schema": { "type": "string" } }, { "name": "limite", "in": "query", "required": false, "description": "1 a 200", "schema": { "type": "string" } }, { "name": "depois", "in": "query", "required": false, "description": "Cursor da página anterior", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "dados": [ { "uuid": "c2d3e4f5-0a1b-4c2d-8e3f-4a5b6c7d8e9f", "ponto_de_coleta": "PTY-COL-0001", "poi": "PTY-POI-0003", "material": "plastico", "peso_gramas": 12400, "coletado_em": "2026-11-02T08:00:00-03:00", "observacao": null, "referencia_externa": "pes-2026-11-02-01", "registrado_em": "2026-11-02T08:01:10-03:00" } ], "pagina": { "limite": 50, "proximo": null, "tem_mais": false } } } } } } } }, "/v1/destinacoes": { "post": { "tags": [ "Resíduos: pontos de coleta, pesagens e destinação" ], "summary": "Registrar a destinação do que foi coletado", "description": "Para onde foi o resíduo, por material. Uma chamada por remessa. É o que fecha o ciclo no painel: coletado e destinado.", "operationId": "post_v1_destinacoes", "servers": [ { "url": "https://api.destinolabparaty.com.br" } ], "security": [ { "bearer": [] } ], "x-escopo": "residuos:escrever", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "1 a 120 caracteres: letras, números e . _ : ~ -", "schema": { "type": "string", "maxLength": 120 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "material": { "description": "Obrigatório: reciclavel, papel, plastico, vidro, metal, organico, rejeito, oleo ou eletronico" }, "peso_gramas": { "description": "Obrigatório. Inteiro, em gramas" }, "destino_tipo": { "description": "Obrigatório: reciclagem, reuso, compostagem, projeto_social, aterro ou outro" }, "destino_nome": { "description": "Cooperativa, projeto ou unidade que recebeu (organização, não pessoa)" }, "destinado_em": { "description": "Obrigatório. ISO 8601 com fuso; não pode estar no futuro" }, "observacao": { "description": "Até 255 caracteres" }, "referencia_externa": { "description": "O id no seu sistema; repetir devolve 200 com o que já existe" } } }, "example": { "material": "plastico", "peso_gramas": 310000, "destino_tipo": "projeto_social", "destino_nome": "Cooperativa de catadores de Paraty", "destinado_em": "2026-11-30T09:00:00-03:00", "referencia_externa": "dest-2026-11" } } } }, "responses": { "200": { "description": "Já existia (repetição)", "content": { "application/json": { "schema": { "type": "object" }, "example": { "criado": true, "uuid": "e5f6a7b8-2c3d-4e4f-8a5b-6c7d8e9f0a1b", "solucao": "reciclo", "material": "plastico", "peso_gramas": 310000, "destino_tipo": "projeto_social", "destino_nome": "Cooperativa de catadores de Paraty", "destinado_em": "2026-11-30T09:00:00-03:00", "observacao": null, "referencia_externa": "dest-2026-11", "registrado_em": "2026-11-30T09:10:00-03:00" } } } }, "201": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "criado": true, "uuid": "e5f6a7b8-2c3d-4e4f-8a5b-6c7d8e9f0a1b", "solucao": "reciclo", "material": "plastico", "peso_gramas": 310000, "destino_tipo": "projeto_social", "destino_nome": "Cooperativa de catadores de Paraty", "destinado_em": "2026-11-30T09:00:00-03:00", "observacao": null, "referencia_externa": "dest-2026-11", "registrado_em": "2026-11-30T09:10:00-03:00" } } } } } }, "get": { "tags": [ "Resíduos: pontos de coleta, pesagens e destinação" ], "summary": "Destinações registradas", "description": "Da mais recente para a mais antiga.", "operationId": "get_v1_destinacoes", "servers": [ { "url": "https://api.destinolabparaty.com.br" } ], "security": [ { "bearer": [] } ], "x-escopo": "residuos:ler", "parameters": [ { "name": "material", "in": "query", "required": false, "description": "Filtra por material", "schema": { "type": "string" } }, { "name": "destino_tipo", "in": "query", "required": false, "description": "Filtra por tipo de destino", "schema": { "type": "string" } }, { "name": "de", "in": "query", "required": false, "description": "Dia inicial, AAAA-MM-DD", "schema": { "type": "string" } }, { "name": "ate", "in": "query", "required": false, "description": "Dia final, AAAA-MM-DD, incluído", "schema": { "type": "string" } }, { "name": "limite", "in": "query", "required": false, "description": "1 a 200", "schema": { "type": "string" } }, { "name": "depois", "in": "query", "required": false, "description": "Cursor da página anterior", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "dados": [ { "uuid": "e5f6a7b8-2c3d-4e4f-8a5b-6c7d8e9f0a1b", "solucao": "reciclo", "material": "plastico", "peso_gramas": 310000, "destino_tipo": "projeto_social", "destino_nome": "Cooperativa de catadores de Paraty", "destinado_em": "2026-11-30T09:00:00-03:00", "observacao": null, "referencia_externa": "dest-2026-11", "registrado_em": "2026-11-30T09:10:00-03:00" } ], "pagina": { "limite": 50, "proximo": null, "tem_mais": false } } } } } } } }, "/v1/pois/{codigo}/conteudos": { "post": { "tags": [ "Conteúdo das soluções e roteiros" ], "summary": "Publicar conteúdo num atrativo", "description": "Precisa de ao menos um entre texto, url e midia. Toda imagem exige texto_alt.", "operationId": "post_v1_pois_codigo_conteudos", "servers": [ { "url": "https://api.destinolabparaty.com.br" } ], "security": [ { "bearer": [] } ], "x-escopo": "conteudo:escrever", "parameters": [ { "name": "codigo", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "1 a 120 caracteres: letras, números e . _ : ~ -", "schema": { "type": "string", "maxLength": 120 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tipo": { "description": "Obrigatório: narrativa, interpretativo, conduta, educativo, memoria ou audio_guia" }, "idioma": { "description": "pt-BR (padrão), en-US, es-ES ou fr-FR" }, "titulo": { "description": "Obrigatório, 2 a 200 caracteres" }, "texto": { "description": "Texto puro, até 20000 caracteres" }, "url": { "description": "Onde o visitante continua a experiência na sua solução (http ou https)" }, "midia": { "description": "tipo (imagem, audio ou video), url e, para imagem, texto_alt" }, "referencia_externa": { "description": "O id no seu sistema; repetir devolve 200 com o que já existe" }, "status": { "description": "publicado (padrão) ou oculto" } } }, "example": { "tipo": "narrativa", "idioma": "pt-BR", "titulo": "A rua que a maré lava", "texto": "Na lua cheia a maré entra pelas ruas do centro. Foi desenhado assim, para lavar a cidade.", "url": "https://historias.destinolabparaty.com.br/centro-historico", "midia": { "tipo": "audio", "url": "https://cdn.exemplo.org/centro-historico.mp3" }, "referencia_externa": "ip-centro-01" } } } }, "responses": { "200": { "description": "Já existia (repetição)", "content": { "application/json": { "schema": { "type": "object" }, "example": { "criado": true, "uuid": "d4e5f6a7-1b2c-4d3e-9f4a-5b6c7d8e9f0a", "poi": "PTY-POI-0001", "solucao": "interact", "tipo": "narrativa", "idioma": "pt-BR", "titulo": "A rua que a maré lava", "texto": "Na lua cheia a maré entra pelas ruas do centro. Foi desenhado assim, para lavar a cidade.", "url": "https://historias.destinolabparaty.com.br/centro-historico", "midia": { "tipo": "audio", "url": "https://cdn.exemplo.org/centro-historico.mp3", "texto_alt": null }, "referencia_externa": "ip-centro-01", "status": "publicado", "atualizado_em": "2026-11-12T10:00:00-03:00" } } } }, "201": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "criado": true, "uuid": "d4e5f6a7-1b2c-4d3e-9f4a-5b6c7d8e9f0a", "poi": "PTY-POI-0001", "solucao": "interact", "tipo": "narrativa", "idioma": "pt-BR", "titulo": "A rua que a maré lava", "texto": "Na lua cheia a maré entra pelas ruas do centro. Foi desenhado assim, para lavar a cidade.", "url": "https://historias.destinolabparaty.com.br/centro-historico", "midia": { "tipo": "audio", "url": "https://cdn.exemplo.org/centro-historico.mp3", "texto_alt": null }, "referencia_externa": "ip-centro-01", "status": "publicado", "atualizado_em": "2026-11-12T10:00:00-03:00" } } } }, "404": { "description": "Atrativo inexistente ou não publicado.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" } } } } } }, "get": { "tags": [ "Conteúdo das soluções e roteiros" ], "summary": "Conteúdos de um atrativo", "description": "Os publicados de todas as soluções (e os ocultos de quem pergunta).", "operationId": "get_v1_pois_codigo_conteudos", "servers": [ { "url": "https://api.destinolabparaty.com.br" } ], "security": [ { "bearer": [] } ], "x-escopo": "catalogo:ler", "parameters": [ { "name": "codigo", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "solucao", "in": "query", "required": false, "description": "cashpago, diaspora, interact, fuba ou reciclo", "schema": { "type": "string" } }, { "name": "tipo", "in": "query", "required": false, "description": "Filtra por tipo", "schema": { "type": "string" } }, { "name": "idioma", "in": "query", "required": false, "description": "Filtra por idioma", "schema": { "type": "string" } }, { "name": "limite", "in": "query", "required": false, "description": "1 a 200", "schema": { "type": "string" } }, { "name": "depois", "in": "query", "required": false, "description": "Cursor da página anterior", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "dados": [ { "uuid": "d4e5f6a7-1b2c-4d3e-9f4a-5b6c7d8e9f0a", "poi": "PTY-POI-0001", "solucao": "interact", "tipo": "narrativa", "idioma": "pt-BR", "titulo": "A rua que a maré lava", "texto": "Na lua cheia a maré entra pelas ruas do centro. Foi desenhado assim, para lavar a cidade.", "url": "https://historias.destinolabparaty.com.br/centro-historico", "midia": { "tipo": "audio", "url": "https://cdn.exemplo.org/centro-historico.mp3", "texto_alt": null }, "referencia_externa": "ip-centro-01", "status": "publicado", "atualizado_em": "2026-11-12T10:00:00-03:00" } ], "pagina": { "limite": 50, "proximo": null, "tem_mais": false } } } } } } } }, "/v1/conteudos/{uuid}": { "get": { "tags": [ "Conteúdo das soluções e roteiros" ], "summary": "Um conteúdo", "description": "Pelo uuid.", "operationId": "get_v1_conteudos_uuid", "servers": [ { "url": "https://api.destinolabparaty.com.br" } ], "security": [ { "bearer": [] } ], "x-escopo": "catalogo:ler", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "uuid": "d4e5f6a7-1b2c-4d3e-9f4a-5b6c7d8e9f0a", "poi": "PTY-POI-0001", "solucao": "interact", "tipo": "narrativa", "idioma": "pt-BR", "titulo": "A rua que a maré lava", "texto": "Na lua cheia a maré entra pelas ruas do centro. Foi desenhado assim, para lavar a cidade.", "url": "https://historias.destinolabparaty.com.br/centro-historico", "midia": { "tipo": "audio", "url": "https://cdn.exemplo.org/centro-historico.mp3", "texto_alt": null }, "referencia_externa": "ip-centro-01", "status": "publicado", "atualizado_em": "2026-11-12T10:00:00-03:00" } } } } } }, "patch": { "tags": [ "Conteúdo das soluções e roteiros" ], "summary": "Alterar um conteúdo", "description": "Só os campos enviados mudam. Os mesmos campos da criação.", "operationId": "patch_v1_conteudos_uuid", "servers": [ { "url": "https://api.destinolabparaty.com.br" } ], "security": [ { "bearer": [] } ], "x-escopo": "conteudo:escrever", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "oculto" } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "oculto", "uuid": "d4e5f6a7-1b2c-4d3e-9f4a-5b6c7d8e9f0a", "poi": "PTY-POI-0001", "solucao": "interact", "tipo": "narrativa", "idioma": "pt-BR", "titulo": "A rua que a maré lava", "texto": "Na lua cheia a maré entra pelas ruas do centro. Foi desenhado assim, para lavar a cidade.", "url": "https://historias.destinolabparaty.com.br/centro-historico", "midia": { "tipo": "audio", "url": "https://cdn.exemplo.org/centro-historico.mp3", "texto_alt": null }, "referencia_externa": "ip-centro-01", "atualizado_em": "2026-11-12T10:00:00-03:00" } } } }, "403": { "description": "O conteúdo foi publicado por outra solução.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" } } } } } }, "delete": { "tags": [ "Conteúdo das soluções e roteiros" ], "summary": "Retirar um conteúdo", "description": "Responde 204. A referencia_externa fica livre para um novo envio.", "operationId": "delete_v1_conteudos_uuid", "servers": [ { "url": "https://api.destinolabparaty.com.br" } ], "security": [ { "bearer": [] } ], "x-escopo": "conteudo:escrever", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Sucesso" }, "403": { "description": "O conteúdo foi publicado por outra solução.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" } } } } } } }, "/v1/roteiros": { "post": { "tags": [ "Conteúdo das soluções e roteiros" ], "summary": "Criar roteiro digital", "description": "As paradas vão na ordem da lista. O código (PTY-ROT-003) é gerado aqui.", "operationId": "post_v1_roteiros", "servers": [ { "url": "https://api.destinolabparaty.com.br" } ], "security": [ { "bearer": [] } ], "x-escopo": "conteudo:escrever", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "1 a 120 caracteres: letras, números e . _ : ~ -", "schema": { "type": "string", "maxLength": 120 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "titulo": { "description": "Obrigatório, 2 a 200 caracteres" }, "resumo": { "description": "Até 500 caracteres" }, "duracao_minutos": { "description": "Inteiro; guardado com precisão de 6 minutos" }, "dificuldade": { "description": "facil, moderada ou dificil" }, "perfil": { "description": "Texto livre curto: familia, aventura, cultural" }, "url_externa": { "description": "O roteiro na sua solução" }, "paradas": { "description": "Obrigatório, 1 a 40: poi (código), tempo_sugerido_min e nota" }, "referencia_externa": { "description": "O id no seu sistema; repetir devolve 200 com o que já existe" }, "status": { "description": "publicado (padrão), rascunho ou arquivado" } } }, "example": { "titulo": "Paraty em histórias", "resumo": "Do cais à praça, a pé, em uma hora e meia.", "duracao_minutos": 90, "dificuldade": "facil", "perfil": "cultural", "paradas": [ { "poi": "PTY-POI-0001", "tempo_sugerido_min": 20, "nota": "Comece aqui." } ], "referencia_externa": "ip-rot-01" } } } }, "responses": { "200": { "description": "Já existia (repetição)", "content": { "application/json": { "schema": { "type": "object" }, "example": { "criado": true, "codigo": "PTY-ROT-003", "slug": "paraty-em-historias-3", "solucao": "interact", "titulo": "Paraty em histórias", "resumo": "Do cais à praça, a pé, em uma hora e meia.", "duracao_minutos": 90, "dificuldade": "facil", "perfil": "cultural", "url_externa": "https://historias.destinolabparaty.com.br/roteiro", "referencia_externa": "ip-rot-01", "status": "publicado", "total_de_paradas": 2, "atualizado_em": "2026-11-12T10:05:00-03:00", "paradas": [ { "ordem": 1, "poi": "PTY-POI-0016", "nome": "Cais de Paraty", "tempo_sugerido_min": 20, "nota": "Comece aqui." }, { "ordem": 2, "poi": "PTY-POI-0008", "nome": "Praça da Matriz", "tempo_sugerido_min": null, "nota": null } ] } } } }, "201": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "criado": true, "codigo": "PTY-ROT-003", "slug": "paraty-em-historias-3", "solucao": "interact", "titulo": "Paraty em histórias", "resumo": "Do cais à praça, a pé, em uma hora e meia.", "duracao_minutos": 90, "dificuldade": "facil", "perfil": "cultural", "url_externa": "https://historias.destinolabparaty.com.br/roteiro", "referencia_externa": "ip-rot-01", "status": "publicado", "total_de_paradas": 2, "atualizado_em": "2026-11-12T10:05:00-03:00", "paradas": [ { "ordem": 1, "poi": "PTY-POI-0016", "nome": "Cais de Paraty", "tempo_sugerido_min": 20, "nota": "Comece aqui." }, { "ordem": 2, "poi": "PTY-POI-0008", "nome": "Praça da Matriz", "tempo_sugerido_min": null, "nota": null } ] } } } } } }, "get": { "tags": [ "Conteúdo das soluções e roteiros" ], "summary": "Roteiros publicados", "description": "Sem as paradas; peça o roteiro pelo código para vê-las.", "operationId": "get_v1_roteiros", "servers": [ { "url": "https://api.destinolabparaty.com.br" } ], "security": [ { "bearer": [] } ], "x-escopo": "catalogo:ler", "parameters": [ { "name": "solucao", "in": "query", "required": false, "description": "Quem assina", "schema": { "type": "string" } }, { "name": "poi", "in": "query", "required": false, "description": "Roteiros que passam por este atrativo", "schema": { "type": "string" } }, { "name": "limite", "in": "query", "required": false, "description": "1 a 200", "schema": { "type": "string" } }, { "name": "depois", "in": "query", "required": false, "description": "Cursor da página anterior", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "dados": [ { "codigo": "PTY-ROT-003", "slug": "paraty-em-historias-3", "solucao": "interact", "titulo": "Paraty em histórias", "resumo": "Do cais à praça, a pé, em uma hora e meia.", "duracao_minutos": 90, "dificuldade": "facil", "perfil": "cultural", "url_externa": "https://historias.destinolabparaty.com.br/roteiro", "referencia_externa": "ip-rot-01", "status": "publicado", "total_de_paradas": 2, "atualizado_em": "2026-11-12T10:05:00-03:00" } ], "pagina": { "limite": 50, "proximo": null, "tem_mais": false } } } } } } } }, "/v1/roteiros/{codigo}": { "get": { "tags": [ "Conteúdo das soluções e roteiros" ], "summary": "Um roteiro, com as paradas", "description": "Pelo código.", "operationId": "get_v1_roteiros_codigo", "servers": [ { "url": "https://api.destinolabparaty.com.br" } ], "security": [ { "bearer": [] } ], "x-escopo": "catalogo:ler", "parameters": [ { "name": "codigo", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "codigo": "PTY-ROT-003", "slug": "paraty-em-historias-3", "solucao": "interact", "titulo": "Paraty em histórias", "resumo": "Do cais à praça, a pé, em uma hora e meia.", "duracao_minutos": 90, "dificuldade": "facil", "perfil": "cultural", "url_externa": "https://historias.destinolabparaty.com.br/roteiro", "referencia_externa": "ip-rot-01", "status": "publicado", "total_de_paradas": 2, "atualizado_em": "2026-11-12T10:05:00-03:00", "paradas": [ { "ordem": 1, "poi": "PTY-POI-0016", "nome": "Cais de Paraty", "tempo_sugerido_min": 20, "nota": "Comece aqui." }, { "ordem": 2, "poi": "PTY-POI-0008", "nome": "Praça da Matriz", "tempo_sugerido_min": null, "nota": null } ] } } } } } }, "put": { "tags": [ "Conteúdo das soluções e roteiros" ], "summary": "Substituir um roteiro", "description": "Troca o roteiro inteiro, com as paradas. O que não vier no corpo sai. Mesmos campos da criação.", "operationId": "put_v1_roteiros_codigo", "servers": [ { "url": "https://api.destinolabparaty.com.br" } ], "security": [ { "bearer": [] } ], "x-escopo": "conteudo:escrever", "parameters": [ { "name": "codigo", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "titulo": "Paraty em histórias", "paradas": [ { "poi": "PTY-POI-0001" } ] } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "codigo": "PTY-ROT-003", "slug": "paraty-em-historias-3", "solucao": "interact", "titulo": "Paraty em histórias", "resumo": "Do cais à praça, a pé, em uma hora e meia.", "duracao_minutos": 90, "dificuldade": "facil", "perfil": "cultural", "url_externa": "https://historias.destinolabparaty.com.br/roteiro", "referencia_externa": "ip-rot-01", "status": "publicado", "total_de_paradas": 2, "atualizado_em": "2026-11-12T10:05:00-03:00", "paradas": [ { "ordem": 1, "poi": "PTY-POI-0016", "nome": "Cais de Paraty", "tempo_sugerido_min": 20, "nota": "Comece aqui." }, { "ordem": 2, "poi": "PTY-POI-0008", "nome": "Praça da Matriz", "tempo_sugerido_min": null, "nota": null } ] } } } }, "403": { "description": "O roteiro é de outra solução.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" } } } } } } }, "/v1/ofertas": { "post": { "tags": [ "Ofertas, grade de saídas e reservas" ], "summary": "Publicar oferta", "description": "O operador precisa estar homologado. O código (PTY-OFR-0021) é gerado aqui.", "operationId": "post_v1_ofertas", "servers": [ { "url": "https://api.destinolabparaty.com.br" } ], "security": [ { "bearer": [] } ], "x-escopo": "ofertas:escrever", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "1 a 120 caracteres: letras, números e . _ : ~ -", "schema": { "type": "string", "maxLength": 120 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "operador": { "description": "Obrigatório. Código do operador homologado que presta o serviço" }, "poi": { "description": "Código do atrativo principal da experiência" }, "titulo": { "description": "Obrigatório, 3 a 200 caracteres" }, "resumo": { "description": "Até 500 caracteres" }, "descricao": { "description": "Texto puro, até 20000 caracteres" }, "duracao_minutos": { "description": "Inteiro" }, "preco_centavos": { "description": "Inteiro, em centavos: R$ 180,00 é 18000" }, "capacidade_saida": { "description": "Pessoas por saída" }, "antecedencia_min_h": { "description": "Horas mínimas de antecedência para reservar" }, "idiomas": { "description": "Lista: pt, en, es, fr, de" }, "inclui": { "description": "Texto de até 4000 caracteres; idem nao_inclui, o_que_levar e politica_cancelamento" }, "url_externa": { "description": "Onde comprar, quando a venda é no site da solução" }, "referencia_externa": { "description": "O id no seu sistema; repetir devolve 200 com o que já existe" }, "status": { "description": "publicada (padrão), rascunho, pausada ou encerrada" } } }, "example": { "operador": "{{operador}}", "poi": "PTY-POI-0001", "titulo": "Passeio de escuna pelas ilhas", "resumo": "Cinco horas, quatro paradas para banho.", "duracao_minutos": 300, "preco_centavos": 18000, "capacidade_saida": 80, "idiomas": [ "pt", "en" ], "referencia_externa": "viva-exp-778" } } } }, "responses": { "200": { "description": "Já existia (repetição)", "content": { "application/json": { "schema": { "type": "object" }, "example": { "criado": true, "codigo": "PTY-OFR-0021", "slug": "passeio-de-escuna-pelas-ilhas-21", "solucao": "cashpago", "operador": "PTY-OPE-0012", "poi": "PTY-POI-0009", "titulo": "Passeio de escuna pelas ilhas", "resumo": "Cinco horas, quatro paradas para banho.", "descricao": null, "duracao_minutos": 300, "preco_centavos": 18000, "moeda": "BRL", "capacidade_saida": 80, "antecedencia_min_h": 2, "idiomas": [ "pt", "en" ], "inclui": "Colete, macarrão e frutas.", "nao_inclui": "Almoço e bebidas.", "o_que_levar": "Protetor solar e toalha.", "politica_cancelamento": "Devolução integral até 24 h antes ou com tempo ruim.", "url_externa": null, "referencia_externa": "viva-exp-778", "status": "publicada", "publicado_em": "2026-11-12T09:00:00-03:00", "atualizado_em": "2026-11-12T09:00:00-03:00" } } } }, "201": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "criado": true, "codigo": "PTY-OFR-0021", "slug": "passeio-de-escuna-pelas-ilhas-21", "solucao": "cashpago", "operador": "PTY-OPE-0012", "poi": "PTY-POI-0009", "titulo": "Passeio de escuna pelas ilhas", "resumo": "Cinco horas, quatro paradas para banho.", "descricao": null, "duracao_minutos": 300, "preco_centavos": 18000, "moeda": "BRL", "capacidade_saida": 80, "antecedencia_min_h": 2, "idiomas": [ "pt", "en" ], "inclui": "Colete, macarrão e frutas.", "nao_inclui": "Almoço e bebidas.", "o_que_levar": "Protetor solar e toalha.", "politica_cancelamento": "Devolução integral até 24 h antes ou com tempo ruim.", "url_externa": null, "referencia_externa": "viva-exp-778", "status": "publicada", "publicado_em": "2026-11-12T09:00:00-03:00", "atualizado_em": "2026-11-12T09:00:00-03:00" } } } } } }, "get": { "tags": [ "Ofertas, grade de saídas e reservas" ], "summary": "Ofertas publicadas", "description": "As publicadas de todas as soluções (e as demais de quem pergunta).", "operationId": "get_v1_ofertas", "servers": [ { "url": "https://api.destinolabparaty.com.br" } ], "security": [ { "bearer": [] } ], "x-escopo": "ofertas:ler", "parameters": [ { "name": "solucao", "in": "query", "required": false, "description": "Quem vende", "schema": { "type": "string" } }, { "name": "operador", "in": "query", "required": false, "description": "Código do operador", "schema": { "type": "string" } }, { "name": "poi", "in": "query", "required": false, "description": "Código do atrativo", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "rascunho, publicada, pausada ou encerrada", "schema": { "type": "string" } }, { "name": "limite", "in": "query", "required": false, "description": "1 a 200", "schema": { "type": "string" } }, { "name": "depois", "in": "query", "required": false, "description": "Cursor da página anterior", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "dados": [ { "codigo": "PTY-OFR-0021", "slug": "passeio-de-escuna-pelas-ilhas-21", "solucao": "cashpago", "operador": "PTY-OPE-0012", "poi": "PTY-POI-0009", "titulo": "Passeio de escuna pelas ilhas", "resumo": "Cinco horas, quatro paradas para banho.", "descricao": null, "duracao_minutos": 300, "preco_centavos": 18000, "moeda": "BRL", "capacidade_saida": 80, "antecedencia_min_h": 2, "idiomas": [ "pt", "en" ], "inclui": "Colete, macarrão e frutas.", "nao_inclui": "Almoço e bebidas.", "o_que_levar": "Protetor solar e toalha.", "politica_cancelamento": "Devolução integral até 24 h antes ou com tempo ruim.", "url_externa": null, "referencia_externa": "viva-exp-778", "status": "publicada", "publicado_em": "2026-11-12T09:00:00-03:00", "atualizado_em": "2026-11-12T09:00:00-03:00" } ], "pagina": { "limite": 50, "proximo": null, "tem_mais": false } } } } } } } }, "/v1/ofertas/{codigo}": { "get": { "tags": [ "Ofertas, grade de saídas e reservas" ], "summary": "Uma oferta", "description": "Pelo código.", "operationId": "get_v1_ofertas_codigo", "servers": [ { "url": "https://api.destinolabparaty.com.br" } ], "security": [ { "bearer": [] } ], "x-escopo": "ofertas:ler", "parameters": [ { "name": "codigo", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "codigo": "PTY-OFR-0021", "slug": "passeio-de-escuna-pelas-ilhas-21", "solucao": "cashpago", "operador": "PTY-OPE-0012", "poi": "PTY-POI-0009", "titulo": "Passeio de escuna pelas ilhas", "resumo": "Cinco horas, quatro paradas para banho.", "descricao": null, "duracao_minutos": 300, "preco_centavos": 18000, "moeda": "BRL", "capacidade_saida": 80, "antecedencia_min_h": 2, "idiomas": [ "pt", "en" ], "inclui": "Colete, macarrão e frutas.", "nao_inclui": "Almoço e bebidas.", "o_que_levar": "Protetor solar e toalha.", "politica_cancelamento": "Devolução integral até 24 h antes ou com tempo ruim.", "url_externa": null, "referencia_externa": "viva-exp-778", "status": "publicada", "publicado_em": "2026-11-12T09:00:00-03:00", "atualizado_em": "2026-11-12T09:00:00-03:00" } } } } } }, "patch": { "tags": [ "Ofertas, grade de saídas e reservas" ], "summary": "Alterar uma oferta", "description": "Só os campos enviados mudam. Os mesmos campos da criação.", "operationId": "patch_v1_ofertas_codigo", "servers": [ { "url": "https://api.destinolabparaty.com.br" } ], "security": [ { "bearer": [] } ], "x-escopo": "ofertas:escrever", "parameters": [ { "name": "codigo", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "preco_centavos": 19000, "status": "pausada" } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "preco_centavos": 19000, "status": "pausada", "codigo": "PTY-OFR-0021", "slug": "passeio-de-escuna-pelas-ilhas-21", "solucao": "cashpago", "operador": "PTY-OPE-0012", "poi": "PTY-POI-0009", "titulo": "Passeio de escuna pelas ilhas", "resumo": "Cinco horas, quatro paradas para banho.", "descricao": null, "duracao_minutos": 300, "moeda": "BRL", "capacidade_saida": 80, "antecedencia_min_h": 2, "idiomas": [ "pt", "en" ], "inclui": "Colete, macarrão e frutas.", "nao_inclui": "Almoço e bebidas.", "o_que_levar": "Protetor solar e toalha.", "politica_cancelamento": "Devolução integral até 24 h antes ou com tempo ruim.", "url_externa": null, "referencia_externa": "viva-exp-778", "publicado_em": "2026-11-12T09:00:00-03:00", "atualizado_em": "2026-11-12T09:00:00-03:00" } } } }, "403": { "description": "A oferta é de outra solução.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" } } } } } } }, "/v1/ofertas/{codigo}/saidas": { "put": { "tags": [ "Ofertas, grade de saídas e reservas" ], "summary": "Substituir a grade de saídas do período", "description": "Mande todas as saídas entre de e ate (até 92 dias, até 500 saídas). Saída do período que não vier some se ninguém reservou; se há reserva, fica cancelada. Não dá para baixar vagas_total abaixo do que já foi reservado.", "operationId": "put_v1_ofertas_codigo_saidas", "servers": [ { "url": "https://api.destinolabparaty.com.br" } ], "security": [ { "bearer": [] } ], "x-escopo": "ofertas:escrever", "parameters": [ { "name": "codigo", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "de": { "description": "Obrigatório. Dia inicial, AAAA-MM-DD (fuso de Paraty)" }, "ate": { "description": "Obrigatório. Dia final, incluído" }, "saidas": { "description": "Obrigatório. Lista de inicio_em, fim_em, vagas_total, preco_centavos, equipamento e status (aberta ou cancelada)" } } }, "example": { "de": "2026-12-27", "ate": "2026-12-27", "saidas": [ { "inicio_em": "2026-12-27T10:00:00-03:00", "fim_em": "2026-12-27T15:00:00-03:00", "vagas_total": 80 } ] } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "dados": [ { "vagas_reservadas": 0, "vagas_livres": 80, "equipamento": null, "oferta": "PTY-OFR-0021", "inicio_em": "2026-12-27T10:00:00-03:00", "fim_em": "2026-12-27T15:00:00-03:00", "vagas_total": 80, "preco_centavos": null, "status": "aberta" } ] } } } }, "409": { "description": "Uma saída já tem mais vagas reservadas do que o novo total.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" } } } } } }, "get": { "tags": [ "Ofertas, grade de saídas e reservas" ], "summary": "Grade de saídas e vagas livres", "description": "Por padrão, de hoje a 30 dias.", "operationId": "get_v1_ofertas_codigo_saidas", "servers": [ { "url": "https://api.destinolabparaty.com.br" } ], "security": [ { "bearer": [] } ], "x-escopo": "ofertas:ler", "parameters": [ { "name": "codigo", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "de", "in": "query", "required": false, "description": "Dia inicial, AAAA-MM-DD", "schema": { "type": "string" } }, { "name": "ate", "in": "query", "required": false, "description": "Dia final, AAAA-MM-DD, incluído", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "dados": [ { "oferta": "PTY-OFR-0021", "inicio_em": "2026-12-27T10:00:00-03:00", "fim_em": "2026-12-27T15:00:00-03:00", "equipamento": "PTY-EQP-0034", "vagas_total": 80, "vagas_reservadas": 12, "vagas_livres": 68, "preco_centavos": null, "status": "aberta" } ] } } } } } } }, "/v1/reservas": { "post": { "tags": [ "Ofertas, grade de saídas e reservas" ], "summary": "Informar uma reserva", "description": "A saída é identificada pela oferta e pelo inicio_em. A reserva pode ser numa oferta de outra solução. Sem vaga, responde 409.", "operationId": "post_v1_reservas", "servers": [ { "url": "https://api.destinolabparaty.com.br" } ], "security": [ { "bearer": [] } ], "x-escopo": "reservas:escrever", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "1 a 120 caracteres: letras, números e . _ : ~ -", "schema": { "type": "string", "maxLength": 120 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "oferta": { "description": "Obrigatório. Código da oferta" }, "inicio_em": { "description": "Obrigatório. O início da saída, ISO 8601 com fuso" }, "quantidade": { "description": "Pessoas, 1 a 500 (padrão 1)" }, "valor_total_centavos": { "description": "Obrigatório. Inteiro, em centavos" }, "status": { "description": "confirmada (padrão), pendente ou paga" }, "sub": { "description": "O sub do visitante na sua solução, quando ele está identificado e autorizou" }, "pagamento_ref": { "description": "Referência do pagamento no seu sistema" }, "referencia_externa": { "description": "O id no seu sistema; repetir devolve 200 com o que já existe" } } }, "example": { "oferta": "{{oferta}}", "inicio_em": "2026-12-27T10:00:00-03:00", "quantidade": 2, "valor_total_centavos": 36000, "referencia_externa": "db-res-5521" } } } }, "responses": { "200": { "description": "Já existia (repetição)", "content": { "application/json": { "schema": { "type": "object" }, "example": { "criado": true, "codigo": "PTY-RSV-000118", "oferta": "PTY-OFR-0021", "inicio_em": "2026-12-27T10:00:00-03:00", "canal": "diaspora", "quantidade": 2, "valor_total_centavos": 36000, "moeda": "BRL", "status": "confirmada", "identificado": false, "pagamento_ref": null, "referencia_externa": "db-res-5521", "pago_em": null, "cancelado_em": null, "cancelado_motivo": null, "criado_em": "2026-12-20T16:40:00-03:00" } } } }, "201": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "criado": true, "codigo": "PTY-RSV-000118", "oferta": "PTY-OFR-0021", "inicio_em": "2026-12-27T10:00:00-03:00", "canal": "diaspora", "quantidade": 2, "valor_total_centavos": 36000, "moeda": "BRL", "status": "confirmada", "identificado": false, "pagamento_ref": null, "referencia_externa": "db-res-5521", "pago_em": null, "cancelado_em": null, "cancelado_motivo": null, "criado_em": "2026-12-20T16:40:00-03:00" } } } }, "409": { "description": "A saída não tem vagas livres suficientes, ou não está aberta.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" } } } } } }, "get": { "tags": [ "Ofertas, grade de saídas e reservas" ], "summary": "Reservas da solução", "description": "As que a solução fez e as que caíram nas ofertas dela, da mais recente para a mais antiga.", "operationId": "get_v1_reservas", "servers": [ { "url": "https://api.destinolabparaty.com.br" } ], "security": [ { "bearer": [] } ], "x-escopo": "reservas:ler", "parameters": [ { "name": "oferta", "in": "query", "required": false, "description": "Código da oferta", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Filtra por status", "schema": { "type": "string" } }, { "name": "limite", "in": "query", "required": false, "description": "1 a 200", "schema": { "type": "string" } }, { "name": "depois", "in": "query", "required": false, "description": "Cursor da página anterior", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "dados": [ { "codigo": "PTY-RSV-000118", "oferta": "PTY-OFR-0021", "inicio_em": "2026-12-27T10:00:00-03:00", "canal": "diaspora", "quantidade": 2, "valor_total_centavos": 36000, "moeda": "BRL", "status": "confirmada", "identificado": false, "pagamento_ref": null, "referencia_externa": "db-res-5521", "pago_em": null, "cancelado_em": null, "cancelado_motivo": null, "criado_em": "2026-12-20T16:40:00-03:00" } ], "pagina": { "limite": 50, "proximo": null, "tem_mais": false } } } } } } } }, "/v1/reservas/{codigo}": { "get": { "tags": [ "Ofertas, grade de saídas e reservas" ], "summary": "Uma reserva", "description": "Visível para quem vendeu e para quem é dono da oferta.", "operationId": "get_v1_reservas_codigo", "servers": [ { "url": "https://api.destinolabparaty.com.br" } ], "security": [ { "bearer": [] } ], "x-escopo": "reservas:ler", "parameters": [ { "name": "codigo", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "codigo": "PTY-RSV-000118", "oferta": "PTY-OFR-0021", "inicio_em": "2026-12-27T10:00:00-03:00", "canal": "diaspora", "quantidade": 2, "valor_total_centavos": 36000, "moeda": "BRL", "status": "confirmada", "identificado": false, "pagamento_ref": null, "referencia_externa": "db-res-5521", "pago_em": null, "cancelado_em": null, "cancelado_motivo": null, "criado_em": "2026-12-20T16:40:00-03:00" } } } } } }, "patch": { "tags": [ "Ofertas, grade de saídas e reservas" ], "summary": "Mudar o status de uma reserva", "description": "Cancelar devolve as vagas à saída. Reserva cancelada, realizada ou no_show não muda mais.", "operationId": "patch_v1_reservas_codigo", "servers": [ { "url": "https://api.destinolabparaty.com.br" } ], "security": [ { "bearer": [] } ], "x-escopo": "reservas:escrever", "parameters": [ { "name": "codigo", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Obrigatório: pendente, confirmada, paga, cancelada, no_show ou realizada" }, "cancelado_motivo": { "description": "Até 300 caracteres, sem dado de pessoa" }, "pagamento_ref": { "description": "Referência do pagamento" } } }, "example": { "status": "cancelada", "cancelado_motivo": "Mar agitado" } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "cancelada", "cancelado_em": "2026-12-26T18:00:00-03:00", "cancelado_motivo": "Mar agitado", "codigo": "PTY-RSV-000118", "oferta": "PTY-OFR-0021", "inicio_em": "2026-12-27T10:00:00-03:00", "canal": "diaspora", "quantidade": 2, "valor_total_centavos": 36000, "moeda": "BRL", "identificado": false, "pagamento_ref": null, "referencia_externa": "db-res-5521", "pago_em": null, "criado_em": "2026-12-20T16:40:00-03:00" } } } }, "409": { "description": "A reserva já está num status final.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" } } } } } } }, "/v1/saidas": { "post": { "tags": [ "Registro de saída e ocorrências" ], "summary": "Registrar uma saída", "description": "Ao partir. O código (PTY-SAI-000342) é gerado aqui.", "operationId": "post_v1_saidas", "servers": [ { "url": "https://api.destinolabparaty.com.br" } ], "security": [ { "bearer": [] } ], "x-escopo": "saidas:escrever", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "1 a 120 caracteres: letras, números e . _ : ~ -", "schema": { "type": "string", "maxLength": 120 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "operador": { "description": "Obrigatório. Código do operador homologado" }, "equipamento": { "description": "Código do equipamento do operador" }, "poi_origem": { "description": "Ponto de embarque ou cabeceira da trilha" }, "partiu_em": { "description": "ISO 8601 com fuso (padrão: agora); não pode estar no futuro" }, "retorno_previsto_em": { "description": "ISO 8601 com fuso, depois da partida" }, "passageiros": { "description": "Obrigatório. Inteiro" }, "tripulantes": { "description": "Inteiro" }, "roteiro": { "description": "Por onde vai, até 500 caracteres" }, "referencia_externa": { "description": "O id no seu sistema; repetir devolve 200 com o que já existe" } } }, "example": { "operador": "{{operador}}", "passageiros": 62, "tripulantes": 4, "retorno_previsto_em": "2026-12-27T15:00:00-03:00", "roteiro": "Ilha Comprida, Lagoa Azul e Praia da Lula", "referencia_externa": "viva-saida-9911" } } } }, "responses": { "200": { "description": "Já existia (repetição)", "content": { "application/json": { "schema": { "type": "object" }, "example": { "criado": true, "codigo": "PTY-SAI-000342", "solucao": "cashpago", "operador": "PTY-OPE-0012", "equipamento": "PTY-EQP-0034", "poi_origem": "PTY-POI-0016", "partiu_em": "2026-12-27T10:02:00-03:00", "retorno_previsto_em": "2026-12-27T15:00:00-03:00", "retorno_em": null, "passageiros": 62, "tripulantes": 4, "roteiro": "Ilha Comprida, Lagoa Azul e Praia da Lula", "status": "aberto", "em_atraso": false, "referencia_externa": "viva-saida-9911" } } } }, "201": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "criado": true, "codigo": "PTY-SAI-000342", "solucao": "cashpago", "operador": "PTY-OPE-0012", "equipamento": "PTY-EQP-0034", "poi_origem": "PTY-POI-0016", "partiu_em": "2026-12-27T10:02:00-03:00", "retorno_previsto_em": "2026-12-27T15:00:00-03:00", "retorno_em": null, "passageiros": 62, "tripulantes": 4, "roteiro": "Ilha Comprida, Lagoa Azul e Praia da Lula", "status": "aberto", "em_atraso": false, "referencia_externa": "viva-saida-9911" } } } } } } }, "/v1/saidas/{codigo}": { "get": { "tags": [ "Registro de saída e ocorrências" ], "summary": "Uma saída", "description": "Só quem registrou vê.", "operationId": "get_v1_saidas_codigo", "servers": [ { "url": "https://api.destinolabparaty.com.br" } ], "security": [ { "bearer": [] } ], "x-escopo": "saidas:escrever", "parameters": [ { "name": "codigo", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "codigo": "PTY-SAI-000342", "solucao": "cashpago", "operador": "PTY-OPE-0012", "equipamento": "PTY-EQP-0034", "poi_origem": "PTY-POI-0016", "partiu_em": "2026-12-27T10:02:00-03:00", "retorno_previsto_em": "2026-12-27T15:00:00-03:00", "retorno_em": null, "passageiros": 62, "tripulantes": 4, "roteiro": "Ilha Comprida, Lagoa Azul e Praia da Lula", "status": "aberto", "em_atraso": false, "referencia_externa": "viva-saida-9911" } } } } } }, "patch": { "tags": [ "Registro de saída e ocorrências" ], "summary": "Informar o retorno", "description": "Mandar retorno_em encerra a saída. Também corrige passageiros, tripulantes, roteiro e retorno previsto.", "operationId": "patch_v1_saidas_codigo", "servers": [ { "url": "https://api.destinolabparaty.com.br" } ], "security": [ { "bearer": [] } ], "x-escopo": "saidas:escrever", "parameters": [ { "name": "codigo", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "retorno_em": { "description": "ISO 8601 com fuso, entre a partida e agora; encerra a saída" }, "retorno_previsto_em": { "description": "Nova previsão" }, "passageiros": { "description": "Correção da contagem; idem tripulantes e roteiro" }, "status": { "description": "aberto, atrasado ou encerrado" } } }, "example": { "retorno_em": "2026-12-27T14:52:00-03:00" } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "retorno_em": "2026-12-27T14:52:00-03:00", "status": "encerrado", "codigo": "PTY-SAI-000342", "solucao": "cashpago", "operador": "PTY-OPE-0012", "equipamento": "PTY-EQP-0034", "poi_origem": "PTY-POI-0016", "partiu_em": "2026-12-27T10:02:00-03:00", "retorno_previsto_em": "2026-12-27T15:00:00-03:00", "passageiros": 62, "tripulantes": 4, "roteiro": "Ilha Comprida, Lagoa Azul e Praia da Lula", "em_atraso": false, "referencia_externa": "viva-saida-9911" } } } }, "409": { "description": "A saída já foi encerrada.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" } } } } } } }, "/v1/saidas/em-aberto": { "get": { "tags": [ "Registro de saída e ocorrências" ], "summary": "Saídas que ainda não voltaram", "description": "Consulta da gestão e da Defesa Civil. em_atraso é verdadeiro quando o retorno previsto já passou.", "operationId": "get_v1_saidas_em_aberto", "servers": [ { "url": "https://api.destinolabparaty.com.br" } ], "security": [ { "bearer": [] } ], "x-escopo": "painel:ler", "parameters": [ { "name": "limite", "in": "query", "required": false, "description": "1 a 200", "schema": { "type": "string" } }, { "name": "depois", "in": "query", "required": false, "description": "Cursor da página anterior", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "dados": [ { "codigo": "PTY-SAI-000342", "solucao": "cashpago", "operador": "PTY-OPE-0012", "equipamento": "PTY-EQP-0034", "poi_origem": "PTY-POI-0016", "partiu_em": "2026-12-27T10:02:00-03:00", "retorno_previsto_em": "2026-12-27T15:00:00-03:00", "retorno_em": null, "passageiros": 62, "tripulantes": 4, "roteiro": "Ilha Comprida, Lagoa Azul e Praia da Lula", "status": "aberto", "em_atraso": false, "referencia_externa": "viva-saida-9911" } ], "pagina": { "limite": 50, "proximo": null, "tem_mais": false } } } } } } } }, "/v1/ocorrencias": { "post": { "tags": [ "Registro de saída e ocorrências" ], "summary": "Abrir ocorrência", "description": "Numa saída, num atrativo ou nos dois. A saída passa ao status ocorrencia. Não escreva nome de pessoa na descrição.", "operationId": "post_v1_ocorrencias", "servers": [ { "url": "https://api.destinolabparaty.com.br" } ], "security": [ { "bearer": [] } ], "x-escopo": "saidas:escrever", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "1 a 120 caracteres: letras, números e . _ : ~ -", "schema": { "type": "string", "maxLength": 120 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "saida": { "description": "Código da saída (uma das duas: saida ou poi)" }, "poi": { "description": "Código do atrativo" }, "tipo": { "description": "Obrigatório: atraso, pane, acidente, clima, resgate, extravio ou outro" }, "gravidade": { "description": "baixa (padrão), media, alta ou critica" }, "descricao": { "description": "Obrigatório, 5 a 2000 caracteres" }, "orgaos_acionados": { "description": "Defesa Civil, Capitania, Bombeiros, SAMU" } } }, "example": { "saida": "{{saida}}", "tipo": "pane", "gravidade": "media", "descricao": "Motor parou perto da Ilha Comprida." } } } }, "responses": { "201": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "codigo": "PTY-OCR-00007", "solucao": "cashpago", "saida": "PTY-SAI-000342", "poi": null, "tipo": "pane", "gravidade": "media", "descricao": "Motor parou perto da Ilha Comprida.", "orgaos_acionados": null, "aberta_em": "2026-12-27T12:10:00-03:00", "encerrada_em": null } } } } } } }, "/v1/passaporte/carimbos": { "post": { "tags": [ "Passaporte" ], "summary": "Carimbar o passaporte", "description": "201 com criado: true e as conquistas novas; 200 se o carimbo já existia (um por visitante, atrativo e solução).", "operationId": "post_v1_passaporte_carimbos", "servers": [ { "url": "https://api.destinolabparaty.com.br" } ], "security": [ { "bearer": [] } ], "x-escopo": "passaporte:escrever", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "sub": "VGhpcyBpcyBhIHBhaXJ3aXNlIHN1YmplY3QgaWQ", "poi": "PTY-POI-0001", "origem": "qr" } } } }, "responses": { "200": { "description": "Já existia (repetição)", "content": { "application/json": { "schema": { "type": "object" }, "example": { "criado": true, "conquistas": [ "primeiro_carimbo" ] } } } }, "201": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "criado": true, "conquistas": [ "primeiro_carimbo" ] } } } }, "403": { "description": "O visitante não autorizou esta solução a carimbar.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" } } } }, "404": { "description": "Nenhum visitante com este sub no setor da solução.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" } } } } } } }, "/v1/passaporte/conquistas": { "get": { "tags": [ "Passaporte" ], "summary": "Catálogo de conquistas", "description": "Pública. As conquistas e as regras que as liberam.", "operationId": "get_v1_passaporte_conquistas", "servers": [ { "url": "https://api.destinolabparaty.com.br" } ], "security": [], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "dados": [ { "codigo": "primeiro_carimbo", "nome": "Primeiro carimbo", "descricao": "Você começou o seu Passaporte Destino Paraty.", "regra": { "tipo": "total", "minimo": 1 } } ] } } } } } } }, "/v1/operadores": { "get": { "tags": [ "Operadores, equipamentos e selos" ], "summary": "Listar operadores", "description": "Só os homologados (a curadoria vê todos).", "operationId": "get_v1_operadores", "servers": [ { "url": "https://api.destinolabparaty.com.br" } ], "security": [ { "bearer": [] } ], "x-escopo": "operadores:ler", "parameters": [ { "name": "categoria", "in": "query", "required": false, "description": "nautico_escuna, nautico_barco, nautico_lancha, jipe, guia, receptivo, hospedagem, alimentacao, outro", "schema": { "type": "string" } }, { "name": "busca", "in": "query", "required": false, "description": "Texto no nome", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Só a curadoria", "schema": { "type": "string" } }, { "name": "limite", "in": "query", "required": false, "description": "1 a 200", "schema": { "type": "string" } }, { "name": "depois", "in": "query", "required": false, "description": "Cursor da página anterior", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "dados": [ { "codigo": "PTY-OPE-0012", "nome_fantasia": "Escuna Vitória", "razao_social": "Vitória Passeios Náuticos LTDA", "tipo_pessoa": "juridica", "documento": "**.***.***/0001-**", "categoria": "nautico_escuna", "contato": { "email": "contato@exemplo.org", "telefone": "+55 24 99999-0000", "whatsapp": null }, "cadastur": { "numero": "12.345678.90.0001-2", "situacao": "regular", "validade": "2027-03-01" }, "homologacao": { "status": "homologado", "homologado_em": "2026-10-01T09:00:00-03:00", "homologado_por": "prefeitura-maquina", "motivo_recusa": null }, "comunidade_tradicional": false, "fora_eixo_centro": false, "origem_cadastro": "oficina", "criado_em": "2026-09-20T14:00:00-03:00", "atualizado_em": "2026-10-01T09:00:00-03:00" } ], "pagina": { "limite": 50, "proximo": null, "tem_mais": false } } } } } } }, "post": { "tags": [ "Operadores, equipamentos e selos" ], "summary": "Cadastrar operador", "description": "Nasce pendente. O documento é validado, cifrado e não se repete na base.", "operationId": "post_v1_operadores", "servers": [ { "url": "https://api.destinolabparaty.com.br" } ], "security": [ { "bearer": [] } ], "x-escopo": "operadores:escrever", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "1 a 120 caracteres: letras, números e . _ : ~ -", "schema": { "type": "string", "maxLength": 120 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "nome_fantasia": "Escuna Vitória", "tipo_pessoa": "juridica", "documento": "11.222.333/0001-81", "categoria": "nautico_escuna", "email": "contato@exemplo.org", "telefone": "+55 24 99999-0000", "cadastur": "12.345678.90.0001-2", "cadastur_validade": "2027-03-01", "origem_cadastro": "oficina" } } } }, "responses": { "201": { "description": "Sucesso" } } } }, "/v1/operadores/{codigo}": { "get": { "tags": [ "Operadores, equipamentos e selos" ], "summary": "Detalhe do operador", "description": "Operador não homologado responde 404 para quem não é da curadoria.", "operationId": "get_v1_operadores_codigo", "servers": [ { "url": "https://api.destinolabparaty.com.br" } ], "security": [ { "bearer": [] } ], "x-escopo": "operadores:ler", "parameters": [ { "name": "codigo", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "codigo": "PTY-OPE-0012", "nome_fantasia": "Escuna Vitória", "razao_social": "Vitória Passeios Náuticos LTDA", "tipo_pessoa": "juridica", "documento": "**.***.***/0001-**", "categoria": "nautico_escuna", "contato": { "email": "contato@exemplo.org", "telefone": "+55 24 99999-0000", "whatsapp": null }, "cadastur": { "numero": "12.345678.90.0001-2", "situacao": "regular", "validade": "2027-03-01" }, "homologacao": { "status": "homologado", "homologado_em": "2026-10-01T09:00:00-03:00", "homologado_por": "prefeitura-maquina", "motivo_recusa": null }, "comunidade_tradicional": false, "fora_eixo_centro": false, "origem_cadastro": "oficina", "criado_em": "2026-09-20T14:00:00-03:00", "atualizado_em": "2026-10-01T09:00:00-03:00" } } } } } } }, "/v1/operadores/{codigo}/homologacao": { "post": { "tags": [ "Operadores, equipamentos e selos" ], "summary": "Mudar o status de homologação", "description": "pendente → em_analise → homologado → suspenso. homologado, recusado e suspenso são atos da curadoria; recusado e suspenso exigem motivo.", "operationId": "post_v1_operadores_codigo_homologacao", "servers": [ { "url": "https://api.destinolabparaty.com.br" } ], "security": [ { "bearer": [] } ], "x-escopo": "operadores:escrever", "parameters": [ { "name": "codigo", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "homologado", "cadastur_situacao": "regular" } } } }, "responses": { "200": { "description": "Sucesso" } } } }, "/v1/operadores/{codigo}/equipamentos": { "get": { "tags": [ "Operadores, equipamentos e selos" ], "summary": "Equipamentos do operador", "description": "Com o selo de cada um, quando emitido.", "operationId": "get_v1_operadores_codigo_equipamentos", "servers": [ { "url": "https://api.destinolabparaty.com.br" } ], "security": [ { "bearer": [] } ], "x-escopo": "operadores:ler", "parameters": [ { "name": "codigo", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "dados": [ { "codigo": "PTY-EQP-0034", "tipo": "escuna", "nome": "Vitória V", "registro_capitania": "3811000001", "placa": null, "capacidade_passageiros": 80, "ano_fabricacao": 2012, "status": "ativo", "selo": { "codigo": "PTY-SEL-7K3M9X2QBD", "emitido_em": "2026-11-07T10:00:00-03:00", "validade": "2027-11-07" } } ] } } } } } }, "post": { "tags": [ "Operadores, equipamentos e selos" ], "summary": "Cadastrar equipamento", "description": "Tipos: escuna, lancha, barco, jipe, van, bicicleta, outro.", "operationId": "post_v1_operadores_codigo_equipamentos", "servers": [ { "url": "https://api.destinolabparaty.com.br" } ], "security": [ { "bearer": [] } ], "x-escopo": "operadores:escrever", "parameters": [ { "name": "codigo", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "1 a 120 caracteres: letras, números e . _ : ~ -", "schema": { "type": "string", "maxLength": 120 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "tipo": "escuna", "nome": "Vitória V", "registro_capitania": "3811000001", "capacidade_passageiros": 80, "ano_fabricacao": 2012 } } } }, "responses": { "201": { "description": "Sucesso" } } } }, "/v1/equipamentos/{codigo}/selo": { "post": { "tags": [ "Operadores, equipamentos e selos" ], "summary": "Emitir ou trocar o selo (curadoria)", "description": "O código novo invalida o anterior na hora.", "operationId": "post_v1_equipamentos_codigo_selo", "servers": [ { "url": "https://api.destinolabparaty.com.br" } ], "security": [ { "bearer": [] } ], "x-escopo": "operadores:escrever", "parameters": [ { "name": "codigo", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "validade": "2027-11-07" } } } }, "responses": { "200": { "description": "Sucesso" } } } }, "/v1/selos/{selo_codigo}": { "get": { "tags": [ "Operadores, equipamentos e selos" ], "summary": "Verificar selo", "description": "Pública: é o que o turista confere ao apontar a câmera para o adesivo. situacao: homologado, vencido, suspenso, nao_homologado ou equipamento_inativo. Código desconhecido responde 404.", "operationId": "get_v1_selos_selo_codigo", "servers": [ { "url": "https://api.destinolabparaty.com.br" } ], "security": [], "parameters": [ { "name": "selo_codigo", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "selo": "PTY-SEL-7K3M9X2QBD", "situacao": "homologado", "verificado_em": "2026-11-07T10:30:00-03:00", "operador": { "codigo": "PTY-OPE-0012", "nome": "Escuna Vitória", "categoria": "nautico_escuna" }, "equipamento": { "codigo": "PTY-EQP-0034", "tipo": "escuna", "nome": "Vitória V", "capacidade_passageiros": 80 }, "selo_validade": "2027-11-07" } } } } } } }, "/v1/painel/indicadores": { "get": { "tags": [ "Painel (dashboards)" ], "summary": "Indicadores do destino", "description": "Check-ins (total, pessoas, por solução, por origem e por dia), carimbos, resíduos por material, atrativos publicados, operadores homologados e contas de visitante.", "operationId": "get_v1_painel_indicadores", "servers": [ { "url": "https://api.destinolabparaty.com.br" } ], "security": [ { "bearer": [] } ], "x-escopo": "painel:ler", "parameters": [ { "name": "de", "in": "query", "required": false, "description": "Dia inicial, AAAA-MM-DD (fuso de Paraty)", "schema": { "type": "string" } }, { "name": "ate", "in": "query", "required": false, "description": "Dia final, AAAA-MM-DD, incluído", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "periodo": { "de": "2026-12-01", "ate": "2026-12-31" }, "catalogo": { "pois_publicados": 48 }, "operadores": { "homologados": 165 }, "visitantes": { "contas_ativas": 1240, "contas_novas_no_periodo": 310 }, "checkins": { "total": 5120, "pessoas": 11870, "visitantes_identificados": 640, "pois_com_checkin": 41, "por_solucao": [ { "solucao": "fuba", "total": 1300, "pessoas": 2100 } ], "por_origem": [ { "origem": "qr", "total": 3900, "pessoas": 8200 } ], "por_dia": [ { "dia": "2026-12-27", "total": 412, "pessoas": 980 } ] }, "passaporte": { "carimbos_no_periodo": 2210 }, "residuos": { "pontos_de_coleta_ativos": 36, "coletas": 420, "peso_gramas": 1845300, "por_material": [ { "material": "plastico", "coletas": 140, "peso_gramas": 612400 } ], "destinado_gramas": 1620000, "por_destino": [ { "destino": "reciclagem", "remessas": 12, "peso_gramas": 1100000 } ] }, "conteudo": { "conteudos_publicados": 214, "roteiros_publicados": 9 }, "experiencias": { "ofertas_publicadas": 37, "reservas_no_periodo": 890, "pessoas_reservadas": 2140 }, "seguranca": { "saidas_no_periodo": 1310, "saidas_em_aberto": 6, "ocorrencias_no_periodo": 3 } } } } } } } }, "/v1/painel/pois": { "get": { "tags": [ "Painel (dashboards)" ], "summary": "Indicadores por atrativo", "description": "Todos os atrativos publicados, do mais visitado para o menos, com check-ins, pessoas, carimbos, pontos de coleta ativos e gramas coletados no período.", "operationId": "get_v1_painel_pois", "servers": [ { "url": "https://api.destinolabparaty.com.br" } ], "security": [ { "bearer": [] } ], "x-escopo": "painel:ler", "parameters": [ { "name": "de", "in": "query", "required": false, "description": "Dia inicial, AAAA-MM-DD", "schema": { "type": "string" } }, { "name": "ate", "in": "query", "required": false, "description": "Dia final, AAAA-MM-DD, incluído", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "periodo": { "de": "2026-12-01", "ate": "2026-12-31" }, "dados": [ { "poi": "PTY-POI-0001", "nome": "Centro Histórico de Paraty", "checkins": 820, "pessoas": 1910, "carimbos": 300, "pontos_de_coleta": 4, "residuos_coletados_gramas": 210500 } ] } } } } } } }, "/v1/agenda": { "get": { "tags": [ "Agenda, busca e conteúdo" ], "summary": "Agenda do destino", "description": "Eventos publicados que ainda não acabaram, do mais próximo ao mais distante.", "operationId": "get_v1_agenda", "servers": [ { "url": "https://api.destinolabparaty.com.br" } ], "security": [ { "bearer": [] } ], "x-escopo": "catalogo:ler", "parameters": [ { "name": "de", "in": "query", "required": false, "description": "ISO 8601 com fuso", "schema": { "type": "string" } }, { "name": "ate", "in": "query", "required": false, "description": "ISO 8601 com fuso", "schema": { "type": "string" } }, { "name": "poi", "in": "query", "required": false, "description": "Código do atrativo", "schema": { "type": "string" } }, { "name": "limite", "in": "query", "required": false, "description": "1 a 200", "schema": { "type": "string" } }, { "name": "depois", "in": "query", "required": false, "description": "Cursor", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "dados": [ { "codigo": "PTY-AGD-0012", "slug": "festa-do-divino", "titulo": "Festa do Divino", "resumo": "Procissão e música no Centro Histórico.", "descricao": null, "poi": "PTY-POI-0001", "local": "Igreja Matriz", "inicio_em": "2027-07-28T19:00:00-03:00", "fim_em": "2027-07-28T23:00:00-03:00", "organizador": "Secretaria de Cultura", "gratuito": true, "url_ingressos": null, "imagem_capa": null, "status": "publicado" } ], "pagina": { "limite": 50, "proximo": null, "tem_mais": false } } } } } } }, "post": { "tags": [ "Agenda, busca e conteúdo" ], "summary": "Criar evento (curadoria)", "description": "inicio_em e fim_em exigem fuso. url_ingressos e imagem_capa precisam ser https.", "operationId": "post_v1_agenda", "servers": [ { "url": "https://api.destinolabparaty.com.br" } ], "security": [ { "bearer": [] } ], "x-escopo": "catalogo:escrever", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "1 a 120 caracteres: letras, números e . _ : ~ -", "schema": { "type": "string", "maxLength": 120 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "titulo": "Festa do Divino", "resumo": "Procissão e música no Centro Histórico.", "poi": "PTY-POI-0001", "local": "Igreja Matriz", "inicio_em": "2027-07-28T19:00:00-03:00", "fim_em": "2027-07-28T23:00:00-03:00", "gratuito": true, "status": "publicado" } } } }, "responses": { "201": { "description": "Sucesso" } } } }, "/v1/agenda/{codigo}": { "get": { "tags": [ "Agenda, busca e conteúdo" ], "summary": "Detalhe do evento", "description": "Aceita o código (PTY-AGD-0012) ou o slug.", "operationId": "get_v1_agenda_codigo", "servers": [ { "url": "https://api.destinolabparaty.com.br" } ], "security": [ { "bearer": [] } ], "x-escopo": "catalogo:ler", "parameters": [ { "name": "codigo", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "codigo": "PTY-AGD-0012", "slug": "festa-do-divino", "titulo": "Festa do Divino", "resumo": "Procissão e música no Centro Histórico.", "descricao": null, "poi": "PTY-POI-0001", "local": "Igreja Matriz", "inicio_em": "2027-07-28T19:00:00-03:00", "fim_em": "2027-07-28T23:00:00-03:00", "organizador": "Secretaria de Cultura", "gratuito": true, "url_ingressos": null, "imagem_capa": null, "status": "publicado" } } } } } }, "patch": { "tags": [ "Agenda, busca e conteúdo" ], "summary": "Alterar evento (curadoria)", "description": "Mesmos campos, todos opcionais. status: rascunho, publicado ou cancelado.", "operationId": "patch_v1_agenda_codigo", "servers": [ { "url": "https://api.destinolabparaty.com.br" } ], "security": [ { "bearer": [] } ], "x-escopo": "catalogo:escrever", "parameters": [ { "name": "codigo", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "cancelado" } } } }, "responses": { "200": { "description": "Sucesso" } } } }, "/v1/busca": { "get": { "tags": [ "Agenda, busca e conteúdo" ], "summary": "Busca unificada", "description": "Atrativos, páginas e agenda, até 8 de cada. Ignora acento e caixa e conhece sinônimos locais.", "operationId": "get_v1_busca", "servers": [ { "url": "https://api.destinolabparaty.com.br" } ], "security": [ { "bearer": [] } ], "x-escopo": "catalogo:ler", "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Texto da busca", "schema": { "type": "string" } }, { "name": "idioma", "in": "query", "required": false, "description": "pt-BR, en-US, es-ES ou fr-FR", "schema": { "type": "string" } }, { "name": "limite", "in": "query", "required": false, "description": "1 a 8", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "consulta": "praia", "vazia": false, "pois": [ { "codigo": "PTY-POI-0024", "slug": "praia-brava-de-trindade", "nome": "Praia Brava de Trindade", "resumo": "Praia do conjunto de Trindade, afastada da vila.", "categoria": "praia", "imagem": "https://img.destinolabparaty.com.br/attractions/brava-beach-trindade/exemplo.jpg" } ], "paginas": [ { "slug": "caminho-natureza-que-ensina", "tipo": "guia", "titulo": "Natureza que Ensina", "resumo": "Trilhas, rios e praias com quem sabe ler a floresta e o mar." } ], "agenda": [] } } } } } } }, "/v1/paginas": { "get": { "tags": [ "Agenda, busca e conteúdo" ], "summary": "Páginas editoriais", "description": "Tipos: institucional, guia, noticia, ajuda, legal.", "operationId": "get_v1_paginas", "servers": [ { "url": "https://api.destinolabparaty.com.br" } ], "security": [ { "bearer": [] } ], "x-escopo": "catalogo:ler", "parameters": [ { "name": "tipo", "in": "query", "required": false, "description": "Tipo da página", "schema": { "type": "string" } }, { "name": "idioma", "in": "query", "required": false, "description": "pt-BR, en-US, es-ES ou fr-FR", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso" } } } }, "/v1/paginas/{slug}": { "get": { "tags": [ "Agenda, busca e conteúdo" ], "summary": "Uma página editorial", "description": "O corpo (conteudo) é Markdown. Sem tradução no idioma pedido vem o português, com fallback: true.", "operationId": "get_v1_paginas_slug", "servers": [ { "url": "https://api.destinolabparaty.com.br" } ], "security": [ { "bearer": [] } ], "x-escopo": "catalogo:ler", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "idioma", "in": "query", "required": false, "description": "pt-BR, en-US, es-ES ou fr-FR", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso" } } } }, "/v1/subdominios": { "get": { "tags": [ "Agenda, busca e conteúdo" ], "summary": "Subdomínios das soluções", "description": "Para onde cada subdomínio do destino leva (experiencias., cultura., historias., natureza., circular.).", "operationId": "get_v1_subdominios", "servers": [ { "url": "https://api.destinolabparaty.com.br" } ], "security": [ { "bearer": [] } ], "x-escopo": "catalogo:ler", "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "dados": [ { "host": "cultura.destinolabparaty.com.br", "titulo": "Diaspora.Black", "descricao": "Curadoria da cultura negra", "icone": "cultura", "destino_url": "https://destinolabparaty.com.br/solucoes/diaspora-black", "modo": "redirect", "exibir_no_menu": true, "parceiro": "diaspora" } ] } } } } } } }, "/v1/me": { "get": { "tags": [ "Conta do visitante (token de login)" ], "summary": "Dados do visitante", "description": "sub; com profile: nome, idioma e email_verificado; com email: o e-mail.", "operationId": "get_v1_me", "servers": [ { "url": "https://api.destinolabparaty.com.br" } ], "security": [ { "bearer": [] } ], "x-escopo": "openid", "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "sub": "VGhpcyBpcyBhIHBhaXJ3aXNlIHN1YmplY3QgaWQ", "nome": "Joana", "idioma": "pt-BR", "email_verificado": true } } } } } }, "patch": { "tags": [ "Conta do visitante (token de login)" ], "summary": "Alterar nome e idioma", "description": "Campos: nome e idioma.", "operationId": "patch_v1_me", "servers": [ { "url": "https://api.destinolabparaty.com.br" } ], "security": [ { "bearer": [] } ], "x-escopo": "openid + profile", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "nome": "Joana M.", "idioma": "fr-FR" } } } }, "responses": { "200": { "description": "Sucesso" } } }, "delete": { "tags": [ "Conta do visitante (token de login)" ], "summary": "Eliminar a conta (LGPD, art. 18, VI)", "description": "Anonimiza na hora e revoga todos os tokens. Carimbos e check-ins ficam, sem dono, para a estatística.", "operationId": "delete_v1_me", "servers": [ { "url": "https://api.destinolabparaty.com.br" } ], "security": [ { "bearer": [] } ], "x-escopo": "openid", "responses": { "204": { "description": "Sucesso" } } } }, "/v1/me/email/verificacao": { "post": { "tags": [ "Conta do visitante (token de login)" ], "summary": "Reenviar a confirmação de e-mail", "description": "202 com situacao: enviado ou ja_verificado. Até 3 por hora.", "operationId": "post_v1_me_email_verificacao", "servers": [ { "url": "https://api.destinolabparaty.com.br" } ], "security": [ { "bearer": [] } ], "x-escopo": "openid", "responses": { "202": { "description": "Sucesso" } } } }, "/v1/me/passaporte": { "get": { "tags": [ "Conta do visitante (token de login)" ], "summary": "Passaporte do visitante", "description": "Carimbos e conquistas, com o progresso de cada uma.", "operationId": "get_v1_me_passaporte", "servers": [ { "url": "https://api.destinolabparaty.com.br" } ], "security": [ { "bearer": [] } ], "x-escopo": "passaporte:ler", "responses": { "200": { "description": "Sucesso" } } } }, "/v1/me/consentimentos": { "get": { "tags": [ "Conta do visitante (token de login)" ], "summary": "Consentimentos dados", "description": "O que o visitante autorizou, por aplicação.", "operationId": "get_v1_me_consentimentos", "servers": [ { "url": "https://api.destinolabparaty.com.br" } ], "security": [ { "bearer": [] } ], "x-escopo": "openid", "responses": { "200": { "description": "Sucesso" } } } }, "/v1/me/consentimentos/{client_id}": { "delete": { "tags": [ "Conta do visitante (token de login)" ], "summary": "Revogar um consentimento", "description": "Encerra também os tokens daquela aplicação.", "operationId": "delete_v1_me_consentimentos_client_id", "servers": [ { "url": "https://api.destinolabparaty.com.br" } ], "security": [ { "bearer": [] } ], "x-escopo": "openid", "parameters": [ { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Sucesso" } } } }, "/v1/me/exportacao": { "post": { "tags": [ "Conta do visitante (token de login)" ], "summary": "Exportar os dados (LGPD, art. 18, V)", "description": "JSON com tudo o que o centro guarda sobre o visitante.", "operationId": "post_v1_me_exportacao", "servers": [ { "url": "https://api.destinolabparaty.com.br" } ], "security": [ { "bearer": [] } ], "x-escopo": "openid", "responses": { "200": { "description": "Sucesso" } } } }, "/saude": { "get": { "tags": [ "Saúde" ], "summary": "Processo vivo", "description": "Não toca no banco.", "operationId": "get_saude", "servers": [ { "url": "https://api.destinolabparaty.com.br" } ], "security": [], "responses": { "200": { "description": "Sucesso" } } } }, "/saude/pronto": { "get": { "tags": [ "Saúde" ], "summary": "Pronto para atender", "description": "Confere banco e segredos. 503 se algum falhar.", "operationId": "get_saude_pronto", "servers": [ { "url": "https://api.destinolabparaty.com.br" } ], "security": [], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "ok", "verificacoes": { "segredos": { "ok": true, "ms": 0 }, "banco": { "ok": true, "ms": 22 } }, "horario": "2026-11-10T13:58:00-03:00" } } } } } } } }, "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" }, "clientBasic": { "type": "http", "scheme": "basic", "description": "client_id e client_secret" } }, "schemas": { "Problema": { "type": "object", "description": "RFC 9457", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "request_id": { "type": "string" }, "erros": { "type": "array", "items": { "type": "object", "properties": { "campo": { "type": "string" }, "codigo": { "type": "string" }, "mensagem": { "type": "string" } } } } }, "example": { "type": "https://api.destinolabparaty.com.br/erros/validacao", "title": "Dados inválidos", "status": 422, "detail": "Os dados do check-in são inválidos.", "instance": "/v1/checkins", "request_id": "66f8f763-b272-4d77-b235-c1e692dfe036", "erros": [ { "campo": "nome_do_turista", "codigo": "campo_desconhecido", "mensagem": "Campo não reconhecido." } ] } } } } }