PescaConnect API

API pública de leitura do catálogo de pescarias guiadas da PescaConnect. Não exige autenticação e devolve apenas dados que já aparecem na vitrine do site. Limite de 60 requisições por minuto por endereço IP. As respostas são cacheadas por 5 minutos no CDN, então consulta repetida é barata. Preços em reais, referentes à pescaria inteira e não por pessoa. Versionamento no caminho (/api/v1/). Mudança incompatível entra em /api/v2/, nunca em /api/v1/. Depreciação é sinalizada com os headers Deprecation e Sunset (RFC 8594) por pelo menos 180 dias antes do desligamento, e anunciada em /docs#versionamento.

Especificação OpenAPI 3.1 legível por máquina: /openapi.json. Orientação de uso para agentes: /llms.txt.

Antes de começar

Como ler o resultado sem errar

Dois pontos onde é fácil concluir errado:

Operações

GET/api/v1/fishing-trips

Lista pescarias guiadas disponíveis — listFishingTrips

Devolve pescarias publicadas, com barco aprovado e ao menos uma foto. Use os filtros de cidade, estado, modalidade e preço para estreitar o resultado. A resposta é paginada por limit e offset, e o preço é da pescaria inteira, não por pessoa.

ParâmetroTipoPara que serve
city string Nome da cidade. Casamento parcial, sem distinção de maiúscula. Exemplo: Florianópolis.
state string Sigla da UF, duas letras. Exemplo: SC.
modality string Modalidade da pescaria: oceanica, costeira, aguas-abrigadas, represas ou rios. Exemplo: oceanica.
min_price number Preço mínimo da pescaria inteira, em reais. Exemplo: 400.
max_price number Preço máximo da pescaria inteira, em reais. Exemplo: 2000.
date string Data desejada no formato YYYY-MM-DD. Mantém apenas pescarias com essa data disponível. Exemplo: 2026-12-24.
limit integer Itens por página. Padrão 20, máximo 100. Exemplo: 20.
offset integer Itens a pular. Use junto de limit para paginar. Exemplo: 40. 
curl -sS 'https://pescaconnect.com/api/v1/fishing-trips?city=Florian%C3%B3polis&state=SC&modality=oceanica'

Respostas: 200, 400, 429, 503.

GET/api/v1/fishing-trips/{id}

Detalha uma pescaria — getFishingTrip

Devolve uma pescaria pelo id obtido em listFishingTrips. Responde 404 quando a pescaria não está publicada — ela pode ter sido despublicada pelo barqueiro.

ParâmetroTipoPara que serve
id string (obrigatório) UUID da pescaria. Exemplo: 3f6c8a1e-5b2d-4c7a-9e8f-1a2b3c4d5e6f. 
curl -sS 'https://pescaconnect.com/api/v1/fishing-trips/3f6c8a1e-5b2d-4c7a-9e8f-1a2b3c4d5e6f'

Respostas: 200, 400, 404, 429, 503.

GET/api/v1/cities

Lista cidades com pescaria disponível — listCities

Devolve as cidades que têm pescaria publicada, com a contagem de cada uma e a URL da página da cidade. É o ponto de partida natural: descubra onde há pescaria antes de filtrar qual.

Sem parâmetros.

curl -sS 'https://pescaconnect.com/api/v1/cities'

Respostas: 200, 400, 429, 503.

GET/api/v1/availability

Consulta datas disponíveis de uma pescaria — getAvailability

Devolve as datas futuras em que a pescaria tem vaga aberta, no formato YYYY-MM-DD, incluindo o dia de hoje. Lista vazia significa agenda sem data aberta, não erro.

ParâmetroTipoPara que serve
trip_id string UUID da pescaria. Exemplo: 3f6c8a1e-5b2d-4c7a-9e8f-1a2b3c4d5e6f. 
curl -sS 'https://pescaconnect.com/api/v1/availability?trip_id=3f6c8a1e-5b2d-4c7a-9e8f-1a2b3c4d5e6f'

Respostas: 200, 400, 429, 503.

Erros

Todo erro devolve a mesma forma, e o campo code é o identificador estável — decida por ele, não pela mensagem:

{
  "error": {
    "code": "invalid_limit",
    "message": "O parâmetro limit está fora da faixa aceita.",
    "hint": "Use um inteiro entre 1 e 100. Exemplo: limit=20.",
    "docs": "https://pescaconnect.com/docs#invalid_limit"
  }
}
CodeStatusQuando acontece
invalid_parameter 400 Parâmetro que esta API não aceita, como cursor.
invalid_limit 400 limit fora da faixa de 1 a 100.
invalid_offset 400 offset negativo ou não inteiro.
invalid_price 400 Preço negativo, não numérico, ou min_price maior que max_price.
invalid_date 400 Data fora do formato YYYY-MM-DD.
invalid_state 400 state que não é a sigla de UF com duas letras.
invalid_city 400 Nome de cidade com menos de 2 ou mais de 80 caracteres.
invalid_modality 400 Modalidade com menos de 3 ou mais de 40 caracteres.
invalid_id 400 id ou trip_id que não é UUID.
trip_not_found 404 UUID válido, mas sem pescaria publicada com esse id.
method_not_allowed 405 Método diferente de GET.
rate_limited 429 Acima de 60 requisições por minuto no mesmo IP. Respeite o Retry-After.
source_unavailable 503 A fonte de dados não respondeu. Tente de novo em segundos — não trate como ausência de resultado.

Versionamento e depreciação

A versão vai no caminho: /api/v1/. O compromisso é simples e verificável:

Se você integra com esta API, cheque o header Sunset nas respostas: ele é a forma de a plataforma avisar sem depender de você ler esta página.

Limites e auto-regulação

As respostas trazem os headers do draft IETF de rate limit, para o agente se regular antes de levar erro:

Uma ressalva honesta: o limite é imposto na borda da infraestrutura, antes da aplicação. Quando o corte vem de lá, a resposta é um 429 curto, em texto, sem o corpo JSON descrito abaixo. Decida pelo status, não pelo corpo.

Falar com a gente

Dúvida sobre a API, pedido de limite maior ou proposta de integração: contato@pescaconnect.com.