Desenvolvedores

API de rede

Venda traslados em toda a rede sem contratar operador por operador. Cadastre-se, teste com sua chave ainda hoje e vá para produção após uma revisão.

Integre em um dia

Tudo o que você precisa para testar vem com o cadastro. Ninguém precisa liberar a chave de teste.

Cadastre-se no portal. Você recebe uma chave tmc_test_ na hora: guarde-a, ela só aparece uma vez.
Cote e reserve com ela. Nenhuma frota real participa, nada é cobrado e ninguém é avisado.
Adicione no portal a URL do seu webhook e guarde o segredo, exibido uma só vez.
Reproduza os cenários e confira que seu sistema recebe cada evento.
Sua conta fica em revisão. Uma pessoa a aprova e emite sua chave de produção.

Criar conta de parceiro

curl https://api.transfersmanager.ai/api/v1/channel-api/me \
  -H "X-API-Key: tmc_test_..."

curl -X POST https://api.transfersmanager.ai/api/v1/channel-api/quotes \
  -H "X-API-Key: tmc_test_..." -H "Content-Type: application/json" \
  -d '{"origin_lat":36.68,"origin_lng":-4.49,"destination_lat":36.51,"destination_lng":-4.88,
       "pickup_datetime":"2027-03-14T10:30:00+01:00","passengers":2}'

Com uma chave de produção, a reserva devolve um link de pagamento e entra na rede quando é paga. Só há cotação onde existe oferta real de frotas verificadas: consulte /coverage antes de cotar. Se não houver, /quotes responde 503 no_operators.

Endpoints

Base: /api/v1/channel-api. Autenticação com o cabeçalho X-API-Key ou Authorization: Bearer. Uma referência alheia responde 404, igual a uma inexistente.

GET /me: Quem é esta chave e se é de teste.
GET /coverage: Onde há oferta real: zonas aproximadas, ou a resposta exata para um ponto com lat e lng. Não nomeia frotas.
POST /quotes: Preço com líquido, comissão e total. A cotação vive cinco minutos e reserva uma vez.
POST /bookings: Reserva idempotente por external_ref. Repetir devolve a mesma reserva.
GET /bookings/{ref}: Uma reserva por external_ref ou booking_id.
POST /bookings/{ref}/cancel: Cancela. Sem pagamento, fecha o link. Paga, reembolsa pela escala de cancelamento do operador.
GET /bookings/{ref}/voucher: Dados da reserva para o seu próprio voucher. Não há passe nem PDF: esses documentos nomeiam o operador.
GET /flights/{number}?date=YYYY-MM-DD: Um voo por número e data. 404 flight_not_found se não existir e 503 flight_status_unavailable com Retry-After se não for possível saber.
POST /pickup-suggestion: Quando reservar a coleta para um voo. Não reserva nada nem fixa preço.
POST /test/bookings/{ref}/scenario: Só chaves de teste: reproduz um cenário.
GET /test/bookings/{ref}/events: Só chaves de teste: o que aconteceu em uma reserva de teste.

Chaves de teste

Uma chave tmc_test_ responde com o mesmo contrato a partir de um mundo isolado: a reserva não é um serviço real e nenhuma frota a vê. O preço é uma estimativa em linha reta, marcada com is_approximate. A reserva fica confirmada na hora, sem link de pagamento. Voos e coletas são inventados. Primeiro driver_assigned; depois o resto.

driver_assigned: Um motorista é atribuído.
driver_delayed: Aviso de atraso, com delay_minutes. Só existe no mundo de teste: hoje a produção não emite este evento.
driver_position: Uma posição inventada do carro.
no_show: O motorista chega e o passageiro não aparece.
completed: O serviço é feito até o fim.

curl -X POST https://api.transfersmanager.ai/api/v1/channel-api/test/bookings/my-ref-1/scenario \
  -H "X-API-Key: tmc_test_..." -H "Content-Type: application/json" \
  -d '{"scenario":"driver_assigned"}'

Webhooks

Uma URL por conta, definida no portal. Cada entrega vai assinada com seu segredo, como na API para parceiros, e as chaves de teste também as recebem.

Verifique a assinatura sobre o corpo original, antes de interpretar o JSON.
Novas tentativas com espera crescente de 30 segundos até uma hora, 12 tentativas no total. Enquanto uma tentativa falha, os próximos eventos da sua conta aguardam nessa passagem.
No portal você vê os últimos 50 eventos e pode reenviar qualquer um. O identificador de entrega é mantido para você detectar duplicados. Ficam guardados 30 dias.
Posição ao vivo: booking.driver_position é opcional e vem desligado. Ative no portal. Só é enviado com o carro a caminho, na coleta ou com o passageiro a bordo, no máximo a cada 30 segundos, e leva apenas identificadores da reserva e coordenadas. Uma posição não é reenviada. Um receptor que falha ou demora 1,5 segundo ou mais fica em pausa por 5 minutos.

import crypto from 'node:crypto';

// rawBody: the request body as a string or Buffer, BEFORE JSON.parse.
export function verifyTmSignature(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false; // older than 5 minutes

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${t}.${rawBody}`)
    .digest('hex');

  const a = Buffer.from(expected);
  const b = Buffer.from(parts.v1 ?? '');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Regras

Antecedência mínima: verificada na cotação e na reserva, com a comunidade autônoma das coordenadas da coleta. Se não for possível saber, ou se o endereço as contradizer, aplica-se o mínimo mais rigoroso. Responde 422 lead_time_too_short com o valor e sua base legal. Chaves de teste sempre aplicam o mais rigoroso.
Uma reserva imediata (immediate: true) precisa de coleta em menos de 24 horas e, sem frota acordada, de pelo menos 60 minutos de antecedência.
O contrato não revela a frota: nem na cotação, nem na cobertura, nem no voucher.

{
  "detail": {
    "error": "lead_time_too_short",
    "message": "Pickups in Cataluña must be booked at least 15 minutes ahead.",
    "minimum_minutes": 15,
    "community": "ES-CT",
    "community_name": "Cataluña",
    "legal_basis": "Decreto-ley 9/2022, ..."
  }
}

Limites

Requisições: 120 por minuto e por chave por padrão; 429 acima disso. Chaves de teste dividem um único limite por conta.
Chaves de teste: 3 ativas por conta.
Reservas de teste: 1.000 por conta e 50 eventos por reserva.
Cadastros: 5 por dia por IP.
Cotação: 5 minutos de vida.
/coverage: Até 1.500 zonas de 0,5 grau; pode ficar em cache por 5 minutos.
Webhook: 5 segundos por entrega; 3 para uma posição.

Recursos

Coleção Postman
Registro de alterações
Status do serviço: responde 200 quando a API e seu banco de dados funcionam.

Trabalha com um único operador?

Ver a API para parceiros