Integração e homologação da API Intermitente

01Visão geral

A integração tem três objetos, criados nesta ordem. Os dois primeiros acontecem uma vez por segurado; o terceiro se repete a cada entrega ou corrida.

Ciclo de vida do período

POST   /intermittent/persons/periods              → abre a cobertura, devolve period_id
   │
   ├── POST /intermittent/persons/geolocation     → 1 ponto por minuto enquanto aberto
   │
   ├── PUT  .../periods/{period_id}               → encerra (entrega concluída)
   └── PUT  .../periods/{period_id}/cancel        → cancela (até 2 min após a criação)

02Ambientes e URLs base

Na documentação de endpoints as requisições aparecem com a variável {{ baseVar }}. Ela é o host do ambiente somado ao prefixo /api/integrations:

Montando um endpoint completo a partir da doc — {{ baseVar }}/intermittent/persons/periods em homologação fica:

https://intermittent-web-api.hml.iza.com.vc/api/integrations/intermittent/persons/periods

Todos os endpoints da integração — cadastro e períodos — respondem nesse mesmo host. Basta apontar para uma única URL base por ambiente.

Primeiro teste de conectividade

Vale começar por aqui: confirme que a credencial responde no ambiente certo antes de escrever qualquer código. 200 valida o token e devolve o cadastro do parceiro; 401 indica problema no token.

$ curl -i https://intermittent-web-api.hml.iza.com.vc/api/integrations/partner-info \
    -H "Authorization: Basic $(printf '%s:%s' "$USER_API_ID" "$SECRET_KEY" | base64)"

03Autenticação

Todos os endpoints exigem autenticação Basic. A IZA entrega, na contratação, um User API ID e uma Secret Key. O token é o Base64 da concatenação dos dois separados por dois-pontos.

# credenciais recebidas da IZA
USER_API_ID=df888dae-6a05-400b-94c2-6962c09f7842
SECRET_KEY=la903yX1Hw+r27RZL5DfOCIvFq0qKvhq...

# token = base64("USER_API_ID:SECRET_KEY")
$ printf '%s:%s' "$USER_API_ID" "$SECRET_KEY" | base64

# enviado em toda requisição
Authorization: Basic ZGY4ODhkYWUtNmEwNS00MDBiLTk0YzItNjk2MmMwOWY3ODQyOmxhOTAz...
Content-Type: application/json

A credencial resolve sozinha a organização do parceiro — não existe parâmetro de organização nos payloads. Guarde a Secret Key em cofre de senhas ou storage criptografado.

Validando a credencial

Use GET /partner-info como teste de fumaça antes de qualquer outra coisa: 200 confirma a credencial e devolve o cadastro do parceiro; 401 indica problema no token.

{
  "partner_info": {
    "name": "IZA Tecnologia",
    "doc": "35206922000134",
    "date_begin": "2021-04-07",
    "external_id": "FILIAL 01",
    "address": {
      "street": "Avenida Cidade Jardim", "number": 377,
      "city": "São Paulo", "state": "SP", "postal_code": "01017-040"
    }
  }
}

04Endpoints

Caminhos relativos à URL base do ambiente. Todos exigem o header Authorization.

{
  "doc": "25084932010",           // obrigatório — CPF
  "name": "Maria Souza",          // obrigatório
  "birthed_at": "1992-02-01",      // opcional
  "email": "maria@exemplo.com",   // opcional
  "main_cell_phone": "11999011234" // opcional
}

// request
{ "doc": "25084932010" }

// 201 Created
{ "id": "f5bbc303-3082-42fd-ab5c-9f54dbb75f9a" }

// request — started_at deve ser enviado em tempo real
{
  "doc": "25084932010",
  "started_at": "2026-08-13T14:22:00",
  "timezone": "America/Sao_Paulo"   // opcional, este é o padrão
}

// 201 Created — guarde o id, é ele que encerra e cancela o período
{ "id": "3b5b13ef-374a-4a4c-9b53-b0990d6afa26" }

{ "finished_at": "2026-08-13T14:51:00" }

{
  "doc": "25084932010",
  "datetime": "2026-08-13T14:23:00",
  "lat": "-23.289173",   // 6 casas decimais
  "long": "-47.313065"   // 6 casas decimais
}

05Regras por tipo de contratação

Retroatividade e duração padrão mudam conforme o produto contratado. Confirme qual se aplica ao seu contrato antes de codificar os limites.

O finished_at automático é uma rede de segurança, não o comportamento esperado: o encerramento explícito via PUT é o que reflete a operação real e é o que a conciliação avalia.

Regras que valem para todos

• Realocação de OS: ao transferir uma Ordem de Serviço para outro prestador, os períodos seguintes devem ser criados com o CPF do novo motorista.
• Pedido já iniciado não se cancela nem se transfere: o acidente pode ocorrer no deslocamento até a coleta.
• Entrega cancelada: os períodos seguintes simplesmente não são criados.
• Mobilidade com cobertura de passageiro: o fluxo de API é idêntico ao de cobertura só do motorista — a diferença aparece apenas no sinistro.

06Homologação

As fases são sequenciais e a homologação é concluída na conciliação — é a partir dela que a credencial de produção é liberada.

GET /intermittent/persons/periods
      ?started_at=2026-08-13T08:00:00
      &finished_at=2026-08-13T16:00:00

07Go-live

Aprovada a conciliação, a IZA emite a credencial de produção.

• Nova User API ID / Secret Key de produção recebidas e guardadas em cofre.
• URL base trocada para o host de produção — ver Ambientes.
• GET /partner-info em produção retorna 200 com o cadastro correto.
• Primeiro período real criado e encerrado, conferido via GET /intermittent/persons/periods.
• Monitoramento e alerta de erro ligados sobre as chamadas à IZA.
• Retenção de logs de 30 dias ativa em produção.

08Erros comuns e como tratar