Guia de Integração de API
Documentação clara e prática para integrar a previsão de ETA da NautIA nos seus sistemas. Endpoints, autenticação, exemplos de código e tratamento de erros — tudo que você precisa para começar.
Endpoints Principais
POST /api/v1/eta/predict
Prediz a ETA de um navio com base em dados de posição, destino e condições meteorológicas.
Resposta: JSON com ETA estimada, margem de confiança e timestamp da previsão.
GET /api/v1/eta/vessel/{mmsi}
Obtém a ETA atual de um navio específico (identificado por MMSI).
Resposta: JSON com ETA em tempo real, histórico de atualizações e dados de posição.
GET /api/v1/eta/port/{port-code}
Lista todas as ETAs previstas para um porto específico (ex: PTLIS para Lisboa).
Resposta: JSON com array de navios, ETAs e status de chegada esperada.
POST /api/v1/webhooks/subscribe
Subscreve a atualizações de ETA em tempo real via webhook.
Resposta: JSON com webhook_id, status de subscrição e próximas atualizações esperadas.
Início Rápido
1. Obtenha suas credenciais
API Key e Secret fornecidos após registro.
2. Autentique-se
Use Bearer Token no header Authorization.
3. Faça sua primeira requisição
POST para /api/v1/eta/predict com dados do navio.
4. Processe a resposta
JSON estruturado com ETA e metadados.
Autenticação
Todas as requisições devem incluir um Bearer Token no header Authorization:
Authorization: Bearer YOUR_API_KEY
Obtenha sua API Key na página de credenciais após criar sua conta.
Formato de Requisição/Resposta
Content-Type
application/json
Exemplo de Requisição
{
"mmsi": 123456789,
"destination_port": "PTLIS",
"current_latitude": 38.7223,
"current_longitude": -9.1393
}
Exemplo de Resposta
{
"eta": "2024-03-20T14:30:00Z",
"confidence": 0.92,
"margin_hours": 2.5,
"updated_at": "2024-03-20T10:15:00Z"
}
Exemplos de Código
Python
import requests
api_key = "YOUR_API_KEY"
headers = {
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json"
}
payload = {
"mmsi": 123456789,
"destination_port": "PTLIS"
}
response = requests.post(
"https://api.nautia.com/v1/eta/predict",
json=payload,
headers=headers
)
eta = response.json()["eta"]
print(f"ETA: {eta}")
JavaScript
const apiKey = "YOUR_API_KEY";
const payload = {
mmsi: 123456789,
destination_port: "PTLIS"
};
fetch("https://api.nautia.com/v1/eta/predict", {
method: "POST",
headers: {
"Authorization": `Bearer ${apiKey}`,
"Content-Type": "application/json"
},
body: JSON.stringify(payload)
})
.then(res => res.json())
.then(data => console.log(data.eta))
Tratamento de Erros
A API retorna códigos de status HTTP padrão. Aqui estão os principais:
OK
Requisição bem-sucedida. Resposta contém dados de ETA.
Bad Request
Dados de entrada inválidos. Verifique o formato da requisição.
Unauthorized
API Key inválida ou ausente. Verifique o header Authorization.
Too Many Requests
Limite de requisições excedido. Aguarde antes de tentar novamente.
Server Error
Erro no servidor. Tente novamente em alguns minutos.
Rate Limiting
Para evitar abuso, limitamos requisições por API Key:
- 100 requisições/minuto por API Key
- 10.000 requisições/dia em plano gratuito
- Limites superiores em planos premium
Headers X-RateLimit-* indicam seu uso atual.
Quotas por Plano
Upgrade disponível na sua conta.
Cobertura desta Documentação
Endpoints Principais
Previsão, consulta de navio, porto e webhooks
Autenticação
Bearer Token e gestão de API Keys
Formato JSON
Estrutura de requisição e resposta
Exemplos Práticos
Python, JavaScript e outras linguagens
Tratamento de Erros
Códigos HTTP e estratégias de retry
Rate Limiting
Quotas e limites de requisições
Documentação Técnica Completa
Acesse a referência completa de API, webhooks e exemplos avançados de integração.
Documentação interativa com playground para testar requisições em tempo real.
Precisa de Ajuda?
Nossa equipe técnica está pronta para ajudar com questões de integração, otimização e troubleshooting.
Entrar em Contato com SuporteWebhooks e Atualizações em Tempo Real
Receba atualizações de ETA em tempo real sem necessidade de polling contínuo. Configure webhooks para integrar previsões de chegada diretamente nos seus sistemas operacionais.
O que são Webhooks?
Webhooks são chamadas HTTP automáticas que a NautIA envia para seu servidor sempre que uma atualização de ETA ocorre. Não é necessário verificar continuamente — você recebe os dados assim que estão disponíveis.
Configuração Simples
Defina uma URL de endpoint no painel de controle da NautIA. Nossa plataforma enviará atualizações de ETA para esse endpoint em formato JSON estruturado, pronto para integração.
Benefícios Imediatos
Reduza latência, economize banda passante, e automatize fluxos operacionais. Receba alertas de chegada, atualize dashboards em tempo real, e integre com sistemas TOS instantaneamente.
Exemplo de Payload de Webhook
Quando uma atualização de ETA é disponibilizada, a NautIA envia um webhook com a seguinte estrutura:
{
"event": "eta_updated",
"timestamp": "2026-03-18T14:32:45Z",
"vessel": {
"imo": "9876543",
"name": "MV Atlantic",
"mmsi": "123456789"
},
"port": {
"code": "PTLIS",
"name": "Port of Lisbon",
"region": "Tejo Estuary"
},
"eta": {
"predicted": "2026-03-18T16:45:00Z",
"confidence": 0.92,
"updated_at": "2026-03-18T14:32:45Z",
"margin_of_error_minutes": 12
},
"data_sources": {
"ais": "live_feed",
"weather": "NOAA_Atlantic",
"algorithm_version": "2.1.0"
}
}Tratamento de Retry
Se seu servidor não responder com sucesso (HTTP 2xx), a NautIA tentará novamente automaticamente:
- 1ª Imediatamente após falha
- 2ª 5 minutos depois
- 3ª 30 minutos depois
- 4ª 2 horas depois
Fallback e Segurança
Implemente um fallback para garantir confiabilidade:
- Valide assinaturas HMAC de webhook para autenticação
- Implemente um log persistente de webhooks recebidos
- Use polling de fallback para dados críticos
- Monitore o status de entrega de webhooks
Casos de Uso Comuns
Alertas de Chegada
Receba notificações automáticas quando um navio está se aproximando do porto. Dispare alertas para equipes de cais, pilotos e gestores operacionais.
Dashboard em Tempo Real
Atualize dashboards operacionais instantaneamente com novas previsões de ETA. Mantenha sua equipe sincronizada com informações sempre atualizadas.
Integração com TOS
Integre atualizações de ETA diretamente no seu Terminal Operating System. Automatize agendamento de cais e alocação de recursos.
Notificações a Clientes
Informe agentes marítimos, transitários e clientes sobre chegadas confirmadas. Melhore transparência e experiência do cliente.
Análise e Auditoria
Registre todas as atualizações de ETA para análise histórica. Valide precisão de previsões e otimize processos operacionais.
Automação de Workflow
Dispare automações condicionadas em ETAs (ex: agendar piloto 2 horas antes, reservar cais, notificar equipes especializadas).
Passos para Implementação
Registre seu Endpoint de Webhook
No painel de controle da NautIA, forneça a URL HTTPS de seu servidor que receberá os webhooks (ex: https://seu-dominio.com/webhooks/eta-updates).
Implemente o Handler de Webhook
Desenvolva um endpoint que aceite requisições POST, valide a assinatura HMAC, e processe o payload JSON de atualização de ETA.
Teste em Ambiente de Staging
Use o ambiente de teste da NautIA para enviar webhooks de exemplo. Valide que seu handler recebe, processa e responde corretamente.
Ative em Produção
Após validação, ative webhooks em seu ambiente de produção. Configure monitoramento para garantir entrega confiável de webhooks.
Monitore e Otimize
Acompanhe métricas de entrega, latência de processamento, e qualidade de dados. Otimize seus fluxos com base em dados reais de operação.
Pronto para Implementar Webhooks?
Acesse nossa documentação técnica completa para guias de implementação detalhados, exemplos de código, e suporte técnico especializado.
Solicitar Documentação TécnicaExemplos de Integração
Veja como a NautIA se integra com os principais sistemas portuários, agências marítimas e plataformas de transitários. Exemplos práticos e fluxos de dados reais para acelerar sua implementação.
Integração com Sistema TOS
Conecte a API da NautIA diretamente ao seu Terminal Operating System (TOS) para receber previsões de ETA em tempo real e sincronizar com agendamento de cais.
POST /api/v1/etas
Authorization: Bearer YOUR_API_KEY
Fluxo: AIS → NautIA → Webhook → TOS Dashboard
Integração com Plataforma de Agência
Integre previsões de ETA nas plataformas de agências marítimas para melhorar comunicação com clientes e otimizar planejamento de operações.
GET /api/v1/vessel/{imo}/eta
Content-Type: application/json
Fluxo: Consulta → NautIA → JSON Response → Dashboard de Agência
Integração com Sistema de Transitário
Conecte previsões de ETA aos seus sistemas de logística para melhorar planejamento de entrega e comunicação com clientes finais.
POST /api/v1/shipment/{id}/eta
?vessel_imo=9123456
Fluxo: Shipment ID → NautIA → ETA Atualizada → Cliente
Fluxo de Dados e Mapeamento de Campos
Requisição de Exemplo
{
"vessel_imo": "9123456",
"vessel_call_sign": "CALL1",
"port_code": "PTLIS",
"departure_port": "NLAMS",
"eta_window_start": "2024-03-20T10:00Z",
"eta_window_end": "2024-03-20T14:00Z"
}
Resposta de Exemplo
{
"vessel_imo": "9123456",
"predicted_eta": "2024-03-20T11:45Z",
"confidence_level": 0.94,
"last_position": {
"lat": 38.72,
"lon": -9.14
},
"updated_at": "2024-03-19T15:30Z"
}
Mapeamento de Campos Comuns
| Campo da NautIA | Sistema TOS | Descrição |
|---|---|---|
| vessel_imo | IMO_NUMBER | Número IMO único do navio |
| predicted_eta | ESTIMATED_ARRIVAL | Hora estimada de chegada (ISO 8601) |
| confidence_level | PREDICTION_CONFIDENCE | Nível de confiança (0-1) |
| port_code | PORT_LOCODE | Código LOCODE do porto |
Testes de Integração
- 1. Valide a conectividade com a API usando credentials de teste
- 2. Teste requisições com dados históricos de navios conhecidos
- 3. Verifique webhooks com servidor de teste (ngrok, Postman)
- 4. Compare previsões da NautIA com ETAs reais do histórico
- 5. Valide tratamento de erros e rate limiting
Checklist de Implementação
- API Key configurada e validada
- Endpoints de API documentados e testados
- Webhooks configurados e recebendo eventos
- Tratamento de erros implementado
- Monitoramento e logging em produção
Pronto para Implementar?
Acesse nossa documentação técnica completa com exemplos de código, guias de integração detalhados e suporte da equipe técnica para acelerar sua implementação.
Suporte Técnico
Equipe especializada pronta para ajudar na integração, troubleshooting e otimização da sua implementação NautIA.
Email de Suporte Técnico
Envie suas dúvidas, problemas de integração ou solicitações de consultoria diretamente para nossa equipe técnica.
nautia@nautia.comSLA de Resposta
Issues críticas: resposta em até 4 horas durante horário comercial. Issues padrão: resposta em até 24 horas.
Segunda a sexta, 09:00-18:00 (horário de Lisboa)
Base de Conhecimento
Acesse nossa base de conhecimento com documentação técnica, FAQ, guias de troubleshooting e exemplos de integração.
Disponível 24/7 para autossuficiência e resolução rápida
Comunidade de Desenvolvedores
Conecte-se com outros desenvolvedores, compartilhe soluções e aprenda com casos de uso reais de integração.
Forum e canal de discussão técnica
Consultoria Técnica Especializada
Para implementações complexas, integrações customizadas ou otimizações de desempenho, nossa equipe de especialistas está disponível para consultoria dedicada.
- Análise de arquitetura e design de integração
- Otimização de performance e queries
- Treinamento de equipe técnica
- Suporte pós-implementação e manutenção
Problemas Comuns & Soluções
Erro de Autenticação na API
Se receber erro 401 ao chamar a API, verifique: (1) Sua chave de API está correta e não expirada, (2) O header Authorization está no formato correto: "Bearer {api_key}", (3) Sua chave não foi revogada no painel de controle.
Contatar suporte →Latência Alta em Webhooks
Se seus webhooks estão lentos: (1) Verifique o endpoint do seu servidor está respondendo em menos de 5 segundos, (2) Revise logs de retry — múltiplas tentativas indicam timeout, (3) Considere implementar fila assíncrona para processar payloads em background.
Contatar suporte →Previsão de ETA Não Atualiza
Se a ETA não está sendo atualizada: (1) Confirme que o navio está transmitindo AIS (verifique em MarineTraffic ou similar), (2) Verifique se há dados meteorológicos disponíveis para a rota, (3) Revise o status da sua subscrição e quotas de API.
Contatar suporte →Não encontrou a resposta?
Nossa equipe de suporte técnico está pronta para ajudar. Entre em contato diretamente ou agende uma consulta técnica especializada.