Guia de Abastecimento

Identificar o ponto de abastecimento (o visor da bomba), reservá-lo, autorizar a bomba, acompanhar por callbacks e informar o pagamento. Nos pontos de abastecimento que aceitam troca de preço, a autorização leva o preço que você definir.

Quem participa

Você chama a API da ConectTec por HTTP. A ConectTec encaminha os comandos ao concentrador do posto e devolve o que acontece na pista chamando o seu servidor de callback.

O fluxo em um minuto

O caminho feliz tem 16 passos. O visor da bomba mostra o que o cliente vê no posto. No exemplo, o cliente abastece 30,00 L de gasolina no ponto de abastecimento 3 do posto 4021 e paga R$ 182,70 (R$ 6,09 por litro, com R$ 0,20 de desconto sobre a tabela de R$ 6,29).

Antes de começar

No cadastro a ConectTec entrega a chave de API, o identificador de provedor (providerId) e a lista de postos que você pode usar, cada um com o seu stationId. Você informa a base de callback. A ConectTec também libera, rota por rota, o que o seu cadastro pode chamar: rota não liberada responde 401 sem corpo. O detalhe está em Credenciais e ambiente. A homologação acontece em produção, num posto de testes: Homologação e entrada em produção.

Sete regras valem para todo o guia:

1. O 201 só confirma recebimento. Reserva e autorização respondem 201 assim que a ConectTec recebe o pedido; o resultado chega por callback. Sem o callback de reserva (reason 0): Se a confirmação não chegar.
2. Cada callback é enviado uma vez, no momento do evento. Processe cada callback pelo reason; um estado final não volta atrás, e ignore um reason 0 ou 4 que chegue depois de um estado final. Veja Contrato dos callbacks.
3. Responda exatamente HTTP 200 em menos de 5 segundos. 201, 202, 204 e redirecionamento não contam como recebido, e o corpo da resposta não é lido. Veja Contrato dos callbacks.
4. Antes de repetir um POST, confira o estado da operação anterior. Resposta 500 recebida significa que nada foi criado: tente uma vez. Timeout, 502, 503 ou 504: espere o callback ou a janela do 406. A entrega tem consulta (Conciliar e recuperar entregas). Veja Erros e diagnóstico.
5. O preço aplicado vem em price da entrega. O de tabela vem em pricewithoutdiscount. Cobre pelo total da entrega. Veja Troca de preço e desconto e Receber a entrega.
6. Ponto de abastecimento ocupado responde 406. Depois de uma reserva sua, o ponto de abastecimento só aceita nova reserva sua quando a reserva termina (abastecimento gravado ou callback de encerramento) ou passam reserveTimeOut mais 120 s. Veja Reservar o ponto de abastecimento.
7. Cada entrega fica disponível em GET /Delivery/ByAuthId. Se o posto perde a conexão no meio do abastecimento, o concentrador guarda a entrega e a envia quando a conexão volta, com o dateTime do abastecimento. Veja Conciliar e recuperar entregas.

Suas duas primeiras chamadas

A consulta do QR code confirma chave, liberação da rota e vínculo com o posto. Sem o código de um QR do posto de testes, use GET /V6/ForecourtMap/ById/{stationId}, que usa só o stationId do cadastro.

O codigo tem 7 dígitos numéricos, com zeros à esquerda.

{
  "fuelPointNumber": 3,
  "stationId": 4021
}

Com o stationId e o fuelPointNumber na mão, a segunda chamada reserva o ponto de abastecimento. O reserveId da resposta 201 aparece em todos os callbacks seguintes.

POST /V4/Delivery/Reserve
SecretKeyAuthorization: <SUA_CHAVE>
Content-Type: application/json

{
  "stationId": 4021,
  "fuelPointNumber": 3,
  "providerId": "<SEU_PROVIDER_ID>",
  "reserveTimeOut": 60
}

{
  "reserveId": "b8f2c6e4-1a3d-4f5b-8c7e-9d0a2b4c6e8f",
  "providerId": "7d1e4c2a-5b3f-4e8a-9c6d-2f1a0b9e8d7c",
  "canInovice": false,
  "canReceipt": false,
  "fuelPoint": {
    "preset": true,
    "block": true,
    "configPrice": true,
    "card": false,
    "tag": false,
    "term": false,
    "fuelPointNumber": 3,
    "hoses": [
      { "hoseNumber": 1, "fuel": { "name": "Gasolina Comum", "imagePath": null, "fuelType": 5, "fuelTypeDescription": "gasolina" } },
      { "hoseNumber": 2, "fuel": { "name": "Etanol", "imagePath": null, "fuelType": 1, "fuelTypeDescription": "etanol" } }
    ]
  }
}

O campo se chama canInovice, com essa grafia, e é assim que a API devolve.

Erros da reserva: Reservar o ponto de abastecimento. Callbacks de status: Acompanhar e cancelar.

Conceitos

O vocabulário da pista e do fluxo de abastecimento, com o campo da API que corresponde a cada termo.

A pista: posto, ponto de abastecimento e bico

Um posto tem uma ou mais bombas. Cada bomba tem um ou mais visores, e cada visor é controlado por uma CPU. A API chama o visor de ponto de abastecimento (o visor da bomba) e o identifica por fuelPointNumber. Um ponto de abastecimento tem um ou mais bicos, identificados por hoseNumber. Cada bico entrega um combustível (fuelType) e guarda até quatro preços, um por nível. Você reserva e autoriza o ponto de abastecimento; combustível e preço são do bico.

Na autorização por bico você escolhe o bico; na autorização por tipo, escolhe o combustível e a ConectTec libera todos os bicos desse combustível no ponto de abastecimento (Autorizar o abastecimento). O hoseNumber é o número físico do bico e é o mesmo na reserva, nos callbacks e na entrega. No callback de status ele é uma lista ([0] quando o bico não é identificado); na entrega é um inteiro.

Glossário

Reserva, autorização e entrega

O abastecimento passa por três registros, nesta ordem.

Reserva. Você pede ao posto que separe um ponto de abastecimento para o seu cliente (POST /V4/Delivery/Reserve). A reserva não libera a bomba, não fixa preço e não define limite. Ela garante que o concentrador aceitou o ponto de abastecimento para você e devolve a lista de bicos. A resposta 201 só confirma que a ConectTec recebeu o pedido. A confirmação do posto chega por callback de status com reason 0. A reserva vive por reserveTimeOut segundos (de 1 a 120, escolhido por você). Se o prazo termina sem autorização, o callback traz reason 2. O posto também pode recusar a reserva (reason 1); veja a linha "Se falha" abaixo.

Autorização. Sobre uma reserva já confirmada, você libera a bomba (POST /V2/Delivery/AuthorizeByFuelType ou POST /V2/Delivery/Authorize) e informa o preço por nível, o limite e a periodicidade das atualizações. É aqui que você aplica desconto: o preço vai no corpo da autorização. O preço aplicado vem em price da entrega, e o de tabela em pricewithoutdiscount. Mande uma autorização por reserva. A resposta 201 também só confirma o recebimento; o posto confirma com reason 4. A autorização vive por authTimeOut segundos (de 1 a 200). Se o cliente não abastecer nesse prazo, chega reason 6. Veja Autorizar o abastecimento e Troca de preço e desconto.

Entrega. É o resultado real: o que a bomba entregou. A ConectTec chama o callback FuelPoint/Delivery no seu servidor com volume, preço aplicado, total e encerrantes. A entrega não tem prazo de validade. Se o posto perde a conexão no meio do abastecimento, o concentrador guarda a entrega e a envia quando a conexão volta, com o dateTime do abastecimento. Cada callback é enviado uma vez, e a entrega fica disponível em GET /Delivery/ByAuthId (Contrato dos callbacks). No exemplo do guia, o cliente abastece 30,00 L de gasolina a R$ 6,09 (R$ 6,29 menos o desconto de R$ 0,20) e a entrega traz total de R$ 182,70, com R$ 188,70 sem o desconto. Veja Receber a entrega e Conciliar e recuperar.

O papel do concentrador

O concentrador é o equipamento da ConectTec que liga a ConectTec às bombas do posto. Reserva, autorização e cancelamento passam por ele, e você não fala com ele diretamente. Se o posto perde a conexão no meio do abastecimento, o concentrador guarda a entrega e a envia quando a conexão volta. O campo stationStatus do mapa de pista indica se o concentrador do posto está conectado; a disponibilidade do ponto de abastecimento vem na resposta da reserva.

Exemplo: ler o ponto de abastecimento 3 do posto 4021

Mapa de pista do posto 4021 filtrado no ponto de abastecimento 3. O parâmetro fuelpointNumber é opcional; sem ele a resposta traz todos os pontos de abastecimento.

GET /V6/ForecourtMap/ById/4021?fuelpointNumber=3
SecretKeyAuthorization: <SUA_CHAVE>

{
  "station": {
    "crtlVersion": "1.0.0.0",
    "version": "1.0",
    "canInvoice": false,
    "canReceipt": false,
    "name": "Posto Exemplo",
    "shortName": "Exemplo",
    "cnpj": "11222333000181",
    "street": "Avenida das Bombas",
    "number": 1200,
    "city": "São Paulo",
    "state": "SP",
    "postalCode": "01000000",
    "latitude": -23.55052,
    "longitude": -46.633308,
    "brand": "Exemplo",
    "stationStatus": true,
    "fuelPoints": [
      {
        "preset": true,
        "block": true,
        "configPrice": true,
        "card": false,
        "tag": false,
        "term": false,
        "fuelPointNumber": 3,
        "qrcode": "0004217",
        "hoses": [
          {
            "hoseNumber": 1,
            "fuel": {
              "name": "Gasolina Comum",
              "imagePath": null,
              "fuelType": 5,
              "fuelTypeDescription": "gasolina"
            },
            "price": 6.29,
            "price2": 6.19,
            "price3": 0,
            "price4": 0,
            "updateDate": "2026-11-03T08:10:41"
          },
          {
            "hoseNumber": 2,
            "fuel": {
              "name": "Etanol",
              "imagePath": null,
              "fuelType": 1,
              "fuelTypeDescription": "etanol"
            },
            "price": 4.39,
            "price2": 4.29,
            "price3": 0,
            "price4": 0,
            "updateDate": "2026-11-03T08:10:41"
          }
        ]
      }
    ]
  }
}

• price a price4 são os níveis 1 a 4; aqui só os níveis 1 e 2 existem. O mapa traz o último preço registrado pela ConectTec. O preço de tabela que vale para autorizar chega no callback de status da reserva (reason 0); se o bico vier como [0], autorize sem desconto, no preço de tabela. O preço aplicado é o price da entrega.
• configPrice: o ponto de abastecimento aceita preço diferente do de tabela (Troca de preço e desconto). preset: aceita limite de valor ou de volume na autorização.
• Ordene fuelPoints por fuelPointNumber e hoses por hoseNumber.
• stationStatus false indica concentrador desconectado.

Erros do mapa de pista

Decida pelo status HTTP.

Regras de todas as chamadas: Visão geral. Estados do ponto de abastecimento e da reserva: Máquinas de estado.

Credenciais e ambiente

O que a ConectTec entrega no cadastro, o que você precisa enviar, como autenticar cada chamada e quais regras valem para todos os endpoints.

O que você recebe e o que você envia no cadastro

O cadastro é feito pela ConectTec. Depois dele, você recebe o que a tabela abaixo lista.

Você envia à ConectTec:

Com a base do exemplo, a ConectTec chama estes dois endereços no seu servidor:

• POST https://integracao.suaempresa.com.br/conecttec/8f3k2m9q/V3/FuelPoint/Status (veja Acompanhar e cancelar)
• POST https://integracao.suaempresa.com.br/conecttec/8f3k2m9q/FuelPoint/Delivery (veja Receber a entrega)

Ambiente único e homologação no posto de testes

Existe um único ambiente, o de produção, em https://api.conecttec.com.br. Não há sandbox separado. A sua homologação acontece nesse mesmo endereço, com a chave restrita a um posto de testes: a ConectTec informa o stationId dele no cadastro.

1. Cadastro. Você recebe a chave, o providerId e o stationId do posto de testes.
2. Homologação. Você implementa e valida o fluxo completo somente nesse posto. Siga o roteiro de Homologação e entrada em produção.
3. Aprovação. A ConectTec revisa o resultado.
4. Produção. Depois da aprovação, a ConectTec vincula os postos reais ao seu cadastro e informa os stationId de cada um.

A chave só alcança os postos vinculados ao seu cadastro, antes e depois da homologação. Qualquer outro posto responde 401 no mapa de pista e na consulta por QR code, e 404 na reserva.

Autenticar uma chamada

Toda chamada leva o cabeçalho SecretKeyAuthorization com a chave de API crua, exatamente como a ConectTec entregou: sem Bearer, aspas ou espaços, com a caixa original. A API lê só o cabeçalho SecretKeyAuthorization. A API é só de servidor para servidor.

Esta consulta serve de teste de credencial: com chave correta, rota liberada e posto vinculado, a resposta é 200. Outras respostas: 400 se stationId não for inteiro válido; 500 se o posto não tem pontos de abastecimento cadastrados ou se o cadastro do posto está incompleto. Detalhes em Erros do mapa de pista.

{
  "station": {
    "crtlVersion": "1.0.0.0",
    "version": "1.0",
    "canInvoice": false,
    "canReceipt": false,
    "name": "Posto Exemplo",
    "shortName": "Exemplo",
    "cnpj": "11222333000181",
    "street": "Avenida das Bombas",
    "number": 1200,
    "city": "São Paulo",
    "state": "SP",
    "postalCode": "01000000",
    "latitude": -23.55052,
    "longitude": -46.633308,
    "brand": "Exemplo",
    "stationStatus": true,
    "fuelPoints": [
      {
        "preset": true,
        "block": true,
        "configPrice": true,
        "card": false,
        "tag": false,
        "term": false,
        "fuelPointNumber": 3,
        "qrcode": "0004217",
        "hoses": [
          {
            "hoseNumber": 1,
            "fuel": { "name": "Gasolina Comum", "imagePath": null, "fuelType": 5, "fuelTypeDescription": "gasolina" },
            "price": 6.29,
            "price2": 6.19,
            "price3": 0,
            "price4": 0,
            "updateDate": "2026-11-03T08:10:41"
          },
          {
            "hoseNumber": 2,
            "fuel": { "name": "Etanol", "imagePath": null, "fuelType": 1, "fuelTypeDescription": "etanol" },
            "price": 4.39,
            "price2": 4.29,
            "price3": 0,
            "price4": 0,
            "updateDate": "2026-11-03T08:10:41"
          }
        ]
      }
    ]
  }
}

Entender o 401

A API usa 401 para toda negativa de acesso. Decida pelo status.

Convenções de dados

Rotas

Cada rota é liberada separadamente. Base https://api.conecttec.com.br, cabeçalho SecretKeyAuthorization. Os dois callbacks marcados como recebidos são chamadas da ConectTec à sua base de callback, sem credencial.

Erros e campos de cada rota estão na seção indicada. Visão consolidada em Erros e diagnóstico e Enumerações e limites.

Pontos de atenção

• A base de callback usa HTTPS, tem segmento secreto no caminho e não termina com barra.
• O seu servidor de callback responde exatamente HTTP 200, sem redirecionamento (301/302), em menos de 5 s (201, 202 e 204 não contam como recebido; cada callback é enviado uma vez).

Passo 1 de 6

Descobrir posto e ponto de abastecimento

Antes de reservar, você precisa saber qual stationId e qual fuelPointNumber o cliente está olhando. O QR code do ponto de abastecimento (o visor da bomba) entrega os dois. O mapa de pista descreve o posto inteiro: pontos de abastecimento, bicos, combustíveis e preços de tabela.

Qual rota usar

O QR resolve o ponto de abastecimento; o mapa mostra os combustíveis dele. Para só reservar, o mapa é dispensável: a reserva devolve os bicos do ponto de abastecimento.

A lista de stationId autorizados vem do cadastro (veja Credenciais e ambiente).

O que é o stationId

stationId é o número do posto como a ConectTec informa a você, um inteiro. É o mesmo valor em todas as rotas e callbacks. Posto não vinculado ao seu cadastro responde 401. Termos em Conceitos.

Consultar um QR code

Cada ponto de abastecimento tem um QR code impresso. Esta rota traduz o código em posto e ponto de abastecimento.

Formato do código

O código tem sempre 7 dígitos numéricos, com zeros à esquerda (0004217). Os zeros fazem parte do código; sem eles a consulta responde 400. Um código identifica o ponto de abastecimento, não o bico.

O conteúdo impresso no QR pode trazer mais que os 7 dígitos. O conteúdo do QR do seu cadastro é combinado com a ConectTec; envie à rota só os 7 caracteres do código (^[0-9]{7}$). Letras voltam como 500; tamanho errado volta como 400.

Requisição

Resposta

{
  "fuelPointNumber": 3,
  "stationId": 4021
}

Erros do QR code

QR inexistente responde 401.

Consultar o mapa de pista

Devolve o cadastro do posto: dados do posto, pontos de abastecimento, bicos, combustíveis e preços. O estado do ponto de abastecimento não vem aqui: chega pelos callbacks de status.

Requisição

Resposta

{
  "station": {
    "crtlVersion": "1.0.0.0",
    "version": "1.0",
    "canInvoice": false,
    "canReceipt": false,
    "name": "Posto Exemplo",
    "shortName": "Exemplo",
    "cnpj": "11222333000181",
    "street": "Avenida das Bombas",
    "number": 1200,
    "city": "São Paulo",
    "state": "SP",
    "postalCode": "01000000",
    "latitude": -23.55052,
    "longitude": -46.633308,
    "brand": "Exemplo",
    "stationStatus": true,
    "fuelPoints": [
      {
        "preset": true,
        "block": true,
        "configPrice": true,
        "card": false,
        "tag": false,
        "term": false,
        "fuelPointNumber": 3,
        "qrcode": "0004217",
        "hoses": [
          {
            "hoseNumber": 1,
            "fuel": {
              "name": "Gasolina Comum",
              "imagePath": null,
              "fuelType": 5,
              "fuelTypeDescription": "gasolina"
            },
            "price": 6.29,
            "price2": 6.19,
            "price3": 0,
            "price4": 0,
            "updateDate": "2026-11-03T08:10:41"
          },
          {
            "hoseNumber": 2,
            "fuel": {
              "name": "Etanol",
              "imagePath": null,
              "fuelType": 1,
              "fuelTypeDescription": "etanol"
            },
            "price": 4.39,
            "price2": 4.29,
            "price3": 0,
            "price4": 0,
            "updateDate": "2026-11-03T08:10:41"
          }
        ]
      },
      {
        "preset": true,
        "block": true,
        "configPrice": true,
        "card": false,
        "tag": false,
        "term": false,
        "fuelPointNumber": 4,
        "qrcode": "0004225",
        "hoses": [
          {
            "hoseNumber": 1,
            "fuel": {
              "name": "Gasolina Comum",
              "imagePath": null,
              "fuelType": 5,
              "fuelTypeDescription": "gasolina"
            },
            "price": 6.29,
            "price2": 6.19,
            "price3": 0,
            "price4": 0,
            "updateDate": "2026-11-03T08:10:41"
          },
          {
            "hoseNumber": 2,
            "fuel": {
              "name": "Etanol",
              "imagePath": null,
              "fuelType": 1,
              "fuelTypeDescription": "etanol"
            },
            "price": 4.39,
            "price2": 4.29,
            "price3": 0,
            "price4": 0,
            "updateDate": "2026-11-03T08:10:41"
          }
        ]
      }
    ]
  }
}

As datas vêm sem fuso (2026-11-03T08:10:41); use só para comparar com outra leitura do mesmo campo.

Campos do mapa de pista

Todos os campos estão presentes em toda resposta. Cadastro incompleto: texto vem null ou vazio; número do endereço, latitude e longitude vêm 0.

Objeto station

Objeto fuelPoints[] (ponto de abastecimento)

Objeto hoses[] (bico)

stationStatus: o concentrador está online?

stationStatus vale true quando o concentrador do posto mantém conexão com a ConectTec. Indica se o concentrador do posto está conectado; a disponibilidade do ponto de abastecimento vem na resposta da reserva.

• false indica posto fora do ar.
• O estado do ponto de abastecimento vem dos callbacks de status e da própria reserva.

Preço do mapa e preço da reserva

O preço do mapa é o último registrado, não o da bomba: serve de referência para exibição ("a partir de R$ 6,29") e não para calcular desconto. Pode diferir do preço de tabela da reserva.

O preço que vale para a reserva chega no callback de status de confirmação (reason 0), com os preços por nível de cada bico. É esse que você usa para calcular descontos e enviar na autorização. Se a confirmação vier com hoseNumber [0], autorize sem desconto, no preço de tabela. O preço aplicado é o price da entrega, e o de tabela vem em pricewithoutdiscount.

Erros do mapa de pista

Tabela geral em Erros e diagnóstico.

O QR só muda de ponto de abastecimento se a ConectTec o reassociar; estrutura do posto muda raramente; stationStatus muda quando o posto cai ou volta.

Passo 2 de 6

Reservar o ponto de abastecimento

Segure um ponto de abastecimento para o seu cliente por alguns segundos, antes de autorizar o abastecimento. O 201 da chamada confirma o recebimento; a confirmação da reserva chega no callback de status.

Para que serve e quando chamar

A reserva trava o ponto de abastecimento (o visor da bomba) para você e devolve o reserveId, usado em todo o resto do fluxo. O callback de confirmação traz os preços de tabela do ponto de abastecimento, que você precisa para autorizar e trocar o preço. Chame quando o cliente já escolheu o posto e o ponto de abastecimento (Descobrir posto e ponto de abastecimento). O ponto de abastecimento fica preso para você até a reserva fechar.

Requisição

Cada chamada aceita cria uma reserva nova, com outro reserveId.

POST /V4/Delivery/Reserve
SecretKeyAuthorization: <SUA_CHAVE>
Content-Type: application/json

{
  "stationId": 4021,
  "fuelPointNumber": 3,
  "providerId": "<SEU_PROVIDER_ID>",
  "reserveTimeOut": 60
}

Resposta 201

A resposta descreve o ponto de abastecimento e entrega o reserveId. Ela não traz preço: o preço de tabela vem no callback de confirmação.

{
  "reserveId": "b8f2c6e4-1a3d-4f5b-8c7e-9d0a2b4c6e8f",
  "providerId": "7d1e4c2a-5b3f-4e8a-9c6d-2f1a0b9e8d7c",
  "canInovice": false,
  "canReceipt": false,
  "fuelPoint": {
    "preset": true,
    "block": true,
    "configPrice": true,
    "card": false,
    "tag": false,
    "term": false,
    "fuelPointNumber": 3,
    "hoses": [
      {
        "hoseNumber": 1,
        "fuel": { "name": "Gasolina Comum", "imagePath": null, "fuelType": 5, "fuelTypeDescription": "gasolina" }
      },
      {
        "hoseNumber": 2,
        "fuel": { "name": "Etanol", "imagePath": null, "fuelType": 1, "fuelTypeDescription": "etanol" }
      }
    ]
  }
}

O callback de confirmação pode chegar poucos milissegundos depois da resposta.

Confirmação pelo callback de status

A ConectTec envia POST {base de callback}/V3/FuelPoint/Status para o seu servidor quando o concentrador responde à reserva. Responda HTTP 200 em menos de 5 segundos. Cada callback é enviado uma vez, no momento do evento. Envio e autenticação estão em Contrato dos callbacks.

O resultado vem em reserveId e reason:

Outro reason fora desta tabela é reservado: responda 200 e ignore. Os demais valores de reason (autorização, abastecimento) estão em Máquinas de estado.

Exemplo do callback de reserva aceita, para o ponto de abastecimento 3 com gasolina no bico 1 e etanol no bico 2:

{
  "stationId": 4021,
  "fuelPointNumber": 3,
  "hoseNumber": [1, 2],
  "reserveId": "b8f2c6e4-1a3d-4f5b-8c7e-9d0a2b4c6e8f",
  "authId": null,
  "fuelPointStatus": 1,
  "reason": 0,
  "volume": 0.0,
  "total": 0.0,
  "price": [[6.29, 4.39], [6.19, 4.29]]
}

O corpo completo, com os objetos fuel, tank, attendant e customer, está em Contrato dos callbacks. Na reserva, attendant e customer vêm vazios ou com valores neutros. fuel só vem preenchido quando hoseNumber tem um único bico; com mais de um, fuel.fuelType é 0 e fuel.name é null.

Como ler a matriz de preço

price é uma matriz price[nível][posição]. Cada linha é um nível de preço (a linha 0 é o nível 1, a linha 1 é o nível 2, até 4 níveis). A coluna i é o bico hoseNumber[i], não o número do bico nem a ordem de fuelPoint.hoses da resposta 201. No exemplo, hoseNumber é [1, 2]: coluna 0 é o bico 1, coluna 1 é o bico 2.

Se hoseNumber vier como [0] ou não listar o bico, não há preço por posição: autorize sem desconto, no preço de tabela, e cobre pelo price da entrega. O preço de tabela para autorizar é o da reserva, não o do mapa de pista; ele chega neste callback (Troca de preço e desconto).

Se a confirmação não chegar

A confirmação depende da resposta do concentrador do posto. Espere até 15 segundos a partir do 201, ou até reserveTimeOut se ele for menor. Sem callback, trate a reserva como não confirmada e envie POST /Delivery/Stop com o reserveId (Cancelar), para que uma confirmação atrasada não a reabra. Ignore um reason 0 que chegue depois de 1, 2, 3 ou 12, ou depois de você desistir: um estado final não volta atrás. Repetir o POST /V4/Delivery/Reserve no mesmo ponto de abastecimento nesse intervalo responde 406.

Erros

Decida pelo código HTTP; o corpo do erro não faz parte do contrato.

Com o posto fora do ar, o prazo de Se a confirmação não chegar encerra a tentativa. Formato geral de erros: Erros e diagnóstico.

Quando a reserva expira

Sem autorização em reserveTimeOut segundos, a ConectTec libera o ponto de abastecimento e envia o callback com reason 2 (reserveTimedOut) e o mesmo reserveId. Depois dele, Authorize responde 400. Ao processar o reason 2 você já pode reservar de novo no mesmo ponto de abastecimento, sem esperar reserveTimeOut + 120 s.

Cancelar antes de autorizar

A reserva se cancela com POST /Delivery/Stop e o reserveId (rota descrita em Acompanhar e cancelar).

POST /Delivery/Stop
SecretKeyAuthorization: <SUA_CHAVE>
Content-Type: application/json

{ "reserveId": "b8f2c6e4-1a3d-4f5b-8c7e-9d0a2b4c6e8f" }

O 201 traz um cancelId e confirma o recebimento. Erros da rota: Erros do Stop. O fim da reserva chega com reason 3 (reserveCancelled) ou 8 (stopSuccessful): aceite os dois como cancelamento concluído. Com reason 9 ou 14 o cancelamento não se completou e a reserva ainda expira no prazo de reserveTimeOut. Uma reserva com Stop não aceita autorização (500, ou 400 depois que o callback de encerramento chega); faça uma nova.

Passo 3 de 6

Autorizar o abastecimento

Libere a bomba para o cliente abastecer, com o limite e o preço que você escolheu. O 201 da chamada confirma o recebimento: o resultado chega no callback de status.

Para que serve e quando chamar

A autorização diz ao concentrador do posto qual combustível liberar no ponto de abastecimento reservado, até que limite e a que preço por litro. Ela devolve o authId, que identifica este abastecimento nos callbacks, no informe de pagamento e na consulta da entrega.

Há duas rotas, com os mesmos campos de limite e preço: POST /V2/Delivery/AuthorizeByFuelType aponta o tipo de combustível (padrão) e POST /V2/Delivery/Authorize aponta o número do bico.

Garanta o valor do cliente antes de chamar (pré-autorização, saldo ou pagamento) e use-o como limitValue com limitType "$". Ajuste a cobrança final pelo total da entrega. Se a autorização falhar ou expirar (reason 5, 6 ou 13), desfaça a garantia. Passado o reserveTimeOut a reserva expira e é preciso reservar de novo. Cada rota é liberada separadamente pela ConectTec para o seu cadastro (Credenciais e ambiente); sem a liberação, 401.

Qual rota usar

Campos comuns às duas rotas

Os nomes de campo não diferenciam maiúsculas de minúsculas. Campos fora das tabelas são ignorados.

Autorizar por tipo de combustível

Além dos campos comuns, esta rota tem um campo próprio:

Exemplo: gasolina no ponto de abastecimento 3, limite de R$ 200,00 e desconto de R$ 0,20 por litro nos dois níveis (6,29 e 6,19 viram 6,09 e 5,99).

POST /V2/Delivery/AuthorizeByFuelType
SecretKeyAuthorization: <SUA_CHAVE>
Content-Type: application/json

{
  "reserveId": "b8f2c6e4-1a3d-4f5b-8c7e-9d0a2b4c6e8f",
  "fuelType": 5,
  "limitType": "$",
  "limitValue": 200,
  "price": [[6.09], [5.99]],
  "updateRate": 2,
  "authTimeOut": 120
}

Como o price é lido nesta rota

Uma coluna por linha: uma linha por nível, um preço por linha. No exemplo, nível 1 a 6,09 e nível 2 a 5,99. Envie um preço por linha.

Autorizar por bico

Em vez de fuelType, esta rota recebe:

POST /V2/Delivery/Authorize
SecretKeyAuthorization: <SUA_CHAVE>
Content-Type: application/json

{
  "reserveId": "b8f2c6e4-1a3d-4f5b-8c7e-9d0a2b4c6e8f",
  "hoseNumber": [1],
  "limitType": "$",
  "limitValue": 200,
  "price": [[6.09], [5.99]],
  "updateRate": 2,
  "authTimeOut": 120
}

Como o price é lido nesta rota

A matriz é price[nível][coluna]. Cada linha é um nível de preço. Com um bico em hoseNumber, cada linha tem uma coluna, como no exemplo acima.

O campo price

price é o preço por litro que a bomba cobra nesta autorização, já com qualquer desconto ou acréscimo. O desconto vai no próprio preço por litro, e o valor vale só para esta autorização. O cálculo do desconto está em Troca de preço e desconto.

• Obrigatório sempre. Sem troca de preço, mande os preços de tabela do callback da reserva (Como ler a matriz de preço).
• Todos os níveis, na ordem do callback. A linha 0 é o nível 1, e assim até 4.
• Sem matriz por posição (hoseNumber [0] na confirmação): autorize sem desconto, no preço de tabela da reserva.
• Casas decimais. 2 ou 3, conforme a tabela do posto, nunca mais de 3. Arredonde antes de enviar (Troca de preço e desconto).
• Ponto de abastecimento com configPrice false. A bomba pode cobrar o preço de tabela (resposta da reserva); o preço aplicado vem em price da entrega.
• Preço aplicado. Vem em price da entrega, e o de tabela em pricewithoutdiscount. Cobre pelo total da entrega.

Limite do abastecimento

Envie limitType e limitValue juntos, exceto no caso GNV.

No limite por valor, calcule sobre o preço com desconto enviado em price.

Caso GNV

Em AuthorizeByFuelType, num ponto de abastecimento de GNV sem preset (fuelType 15 e fuelPoint.preset false), a ConectTec libera a bomba sem repassar preço nem limite: a bomba cobra o preço dela e o cliente abastece até parar. O preço aplicado é o price da entrega. price continua obrigatório (envie os preços de tabela); omita limitType e limitValue. Sem teto, o total só é conhecido no fim.

Resposta 201

As duas rotas devolvem o mesmo corpo. O 201 significa que a ConectTec recebeu a autorização e a encaminhou ao concentrador, não que a bomba foi liberada. Só o reason 4 libera o cliente.

{
  "authId": "c3a9e1f7-5d2b-4c8a-b6e4-0f1d3a5c7e9b",
  "reserveId": "b8f2c6e4-1a3d-4f5b-8c7e-9d0a2b4c6e8f"
}

O callback de resultado pode chegar antes de você processar a resposta; nesse caso identifique a autorização pelo reserveId.

Erros

Decida pelo código HTTP; o corpo do erro não faz parte do contrato.

Após timeout, 502, 503 ou 504, confira o estado da operação anterior: espere o callback com reason 4, 5 ou 6 antes de repetir. Sem callback, envie Stop e faça uma nova reserva. Formato geral de erros: Erros e diagnóstico.

O que acontece depois

A ConectTec envia o resultado por POST {base de callback}/V3/FuelPoint/Status para o seu servidor, com o reserveId e, a partir daqui, o authId. Cada callback é enviado uma vez, no momento do evento. Envio e autenticação estão em Contrato dos callbacks. Processe cada callback pelo reason; um estado final não volta atrás, e ignore um reason 4 que chegue depois de um estado final (5, 6 ou 7).

Outro reason fora das tabelas é reservado: responda 200 e ignore. A lista completa de reason e de estados do ponto de abastecimento está em Máquinas de estado.

Depois do reason 4, o fluxo segue assim:

1. Início do abastecimento: chega como callback com fuelPointStatus 4 (em geral com reason 11; não exija o reason), seguido de callbacks de acompanhamento, a cada updateRate segundos, com volume e total parciais (Acompanhar e cancelar).
2. Fim: a entrega fecha o abastecimento. O registro final chega no callback de entrega, com o preço aplicado e o total (Receber a entrega).
3. Pagamento: Informar o pagamento.

Se o reason 4 não chegar em 20 s (ou authTimeOut, se menor), ou se nada chegar até authTimeOut + 10 s (Suas esperas), trate o posto como indisponível e envie POST /Delivery/Stop com o reserveId e o authId.

Se ninguém abastecer

Se ninguém tirar o bico do descanso em authTimeOut segundos, a autorização expira e chega o callback com reason 6. A expiração é definitiva: faça uma nova reserva. Para desistir antes, use POST /Delivery/Stop com o reserveId e o authId (Acompanhar e cancelar); o resultado chega com reason 7 (autorização cancelada), 8 (Stop aceito) ou 9 (Stop falhou), veja Máquinas de estado.

Troca de preço e desconto

Para dar desconto, você envia o preço final no campo price da autorização. O preço aplicado vem em price da entrega, e o de tabela em pricewithoutdiscount.

Como a troca de preço funciona

A troca de preço é o próprio campo price de POST /V2/Delivery/AuthorizeByFuelType (rota padrão) ou de POST /V2/Delivery/Authorize (por bico). O preço vale só para aquela autorização e é o preço final em reais por litro, não um valor de desconto nem um percentual. O restante da chamada (limitType, limitValue, updateRate, authTimeOut, erros) está em Autorizar o abastecimento.

De onde vêm os preços de tabela

A resposta da reserva não traz preço. Os preços de tabela do ponto de abastecimento (o visor da bomba) chegam no callback de status com reason 0, no campo price (veja Confirmação pelo callback de status e Como ler a matriz de preço). Para o ponto de abastecimento 3 do posto de exemplo:

{
  "stationId": 4021,
  "fuelPointNumber": 3,
  "hoseNumber": [1, 2],
  "reserveId": "b8f2c6e4-1a3d-4f5b-8c7e-9d0a2b4c6e8f",
  "reason": 0,
  "price": [[6.29, 4.39], [6.19, 4.29]]
}

Cada linha de price é um nível de preço (até 4). Cada coluna corresponde à posição em hoseNumber, não ao número do bico: no exemplo, a coluna 0 é o bico 1 (gasolina, R$ 6,29 no nível 1 e R$ 6,19 no nível 2) e a coluna 1 é o bico 2 (etanol).

Se o bico escolhido não aparecer em hoseNumber (campo [0], por exemplo), autorize sem desconto, no preço de tabela, e cobre pelo total da entrega. Os preços do mapa de pista (Preços no mapa) são o último valor registrado, não o do momento da reserva; calcule o desconto sempre pelo callback.

A matriz de preço da autorização

price é sempre uma matriz, mesmo com um preço só. As linhas são os níveis de preço, na ordem em que o callback de reserva os trouxe. O que as colunas significam depende da rota:

• Na rota por bico, autorize um bico só. Com mais de uma, repita o mesmo preço em todas as colunas.
• Envie todos os níveis que o callback da reserva trouxe.
• Aplique o mesmo desconto a todas as linhas e combine com a ConectTec, no cadastro, qual nível o posto aplica ao seu cadastro.

Enviar a autorização com o preço trocado

Desconto de R$ 0,20 por litro na gasolina: 6,29 - 0,20 = 6,09 no nível 1 e 6,19 - 0,20 = 5,99 no nível 2. Envie o preço arredondado, com 2 casas, ou 3 quando a tabela vier com 3; nunca mais de 3. A chamada só é aceita depois do callback com reason 0 (antes, a API responde 400) e uma única vez por reserva. Para refazer o preço, cancele com Stop e reserve de novo. Envie sempre limitType e limitValue, exceto em GNV sem preset, que dispensa os dois (Caso GNV).

POST /V2/Delivery/AuthorizeByFuelType
SecretKeyAuthorization: <SUA_CHAVE>
Content-Type: application/json

{
  "reserveId": "b8f2c6e4-1a3d-4f5b-8c7e-9d0a2b4c6e8f",
  "fuelType": 5,
  "price": [[6.09], [5.99]],
  "limitType": "$",
  "limitValue": 200,
  "updateRate": 2,
  "authTimeOut": 120
}

{
  "authId": "c3a9e1f7-5d2b-4c8a-b6e4-0f1d3a5c7e9b",
  "reserveId": "b8f2c6e4-1a3d-4f5b-8c7e-9d0a2b4c6e8f"
}

O 201 só confirma o recebimento. O resultado vem no callback de status: reason 4 (autorizado), 5 (falhou) ou 6 (expirou). Veja Acompanhar e cancelar e Máquinas de estado. Os erros são os de Autorizar o abastecimento. Resposta 500: erro ao processar, repita uma vez. Antes de repetir um POST após timeout, 502, 503 ou 504, confira o estado da operação anterior: aguarde o callback ou a janela do 406 (reserveTimeOut + 120 s).

A mesma troca pela rota por bico, para o bico 1 (hoseNumber é lista, e cada linha de price tem uma coluna):

POST /V2/Delivery/Authorize
SecretKeyAuthorization: <SUA_CHAVE>
Content-Type: application/json

{
  "reserveId": "b8f2c6e4-1a3d-4f5b-8c7e-9d0a2b4c6e8f",
  "hoseNumber": [1],
  "price": [[6.09], [5.99]],
  "limitType": "$",
  "limitValue": 200,
  "updateRate": 2,
  "authTimeOut": 120
}

Preço enviado

Envie preço maior que zero e, se a regra for só desconto, no máximo o preço de tabela do mesmo bico e do mesmo nível.

Quando a troca de preço não vale

• Ponto de abastecimento com configPrice igual a false. O campo vem na resposta da reserva (fuelPoint.configPrice) e no mapa de pista. O ponto de abastecimento não aceita preço diferente da tabela. Enviar não gera erro, mas a cobrança sai pela tabela.
• GNV em ponto de abastecimento sem preset (fuelType 15 e fuelPoint.preset igual a false). Preço e limite enviados não se aplicam; a bomba cobra o preço dela.
• Equipamento do posto. Em alguns postos a bomba cobra pela tabela; o preço aplicado vem em price da entrega.

O preço cobrado na entrega

O callback de entrega (POST {base de callback}/FuelPoint/Delivery, veja Receber a entrega) traz o que a bomba cobrou. Campos que importam aqui:

{
  "stationId": 4021,
  "fuelPointNumber": 3,
  "hoseNumber": 1,
  "reserveId": "b8f2c6e4-1a3d-4f5b-8c7e-9d0a2b4c6e8f",
  "authId": "c3a9e1f7-5d2b-4c8a-b6e4-0f1d3a5c7e9b",
  "dateTime": "2026-11-03T14:22:05-03:00",
  "volume": 30.0,
  "price": 6.09,
  "total": 182.7,
  "pricewithoutdiscount": 6.29
}

Aqui a bomba aplicou o desconto: price é 6,09, contra pricewithoutdiscount 6,29.

Compare price com todos os preços que você enviou para aquele ponto de abastecimento (diferença menor que R$ 0,0005). Igual a um deles: desconto aplicado. Igual a um preço de tabela e diferente dos enviados: a cobrança saiu pela tabela. Em qualquer caso, cobre pelo total da entrega. Entrega com authId que não é seu segue Conciliar e recuperar entregas.

Se a cobrança saiu pela tabela

O abastecimento já aconteceu e a bomba cobrou o total dela; a reparação ao cliente é do seu fluxo. Se o problema se repetir no mesmo posto ou no mesmo ponto de abastecimento, envie à ConectTec stationId, fuelPointNumber, hoseNumber, reserveId, authId, o price enviado, o recebido e dateTime.

Passo 4 de 6

Acompanhar e cancelar

Depois de autorizar, o que acontece no ponto de abastecimento (o visor da bomba) chega a você pelo callback de status. Cobre o significado de cada callback, os prazos de espera e o cancelamento com POST /Delivery/Stop.

Como o acompanhamento funciona

O estado da reserva chega pelos callbacks de status: a ConectTec avisa por POST {base de callback}/V3/FuelPoint/Status enquanto existe uma reserva ou autorização sua no ponto de abastecimento. O corpo completo está em Contrato dos callbacks.

• Cada callback traz reason (o que aconteceu com a reserva ou a autorização) e fuelPointStatus (como o ponto de abastecimento está). Decida primeiro pelo reason; o reserveId identifica a reserva.
• Cada callback é enviado uma vez, no momento do evento. Processe cada callback pelo reason; um estado final não volta atrás, e ignore um reason 0 ou 4 que chegue depois de um estado final. O estado seguinte chega no próximo callback; a entrega fecha o abastecimento. Autentique o callback pelo segmento secreto na base de callback, HTTPS e a conferência do reserveId/authId contra as suas operações (veja Contrato dos callbacks).
• O callback pode chegar antes de você gravar a reserva. Responda 200 e reprocesse em alguns segundos.

Sequência de um abastecimento normal de 30,00 L de gasolina a R$ 6,09 no ponto de abastecimento 3 do posto 4021.

O que chegou e o que fazer

O fuelPointStatus indica andamento só quando é 4 (em geral com reason 11, que você não precisa exigir). Os reason 1, 2, 3, 5, 6, 7, 8, 12 e 13 encerram a reserva ou a autorização, qualquer que seja o status do ponto de abastecimento; os 9 e 14 e os valores desconhecidos não mudam nada. Se a reserva já estava abastecendo, a entrega pode chegar com o volume parcial.

Os valores de reason que não aparecem na tabela são reservados. A lista completa de valores está em Máquinas de estado.

O fim chega pela entrega

Quando o frentista devolve o bico ao descanso, o posto fecha o abastecimento e a ConectTec envia POST {base de callback}/FuelPoint/Delivery. Esse callback é o fim do abastecimento: traz volume, valor, preço aplicado, encerrantes e a data. Os campos e as regras de conferência estão em Receber a entrega.

Se o posto perde a conexão no meio do abastecimento, o concentrador guarda a entrega e a envia quando a conexão volta, com o dateTime do abastecimento. A entrega fica disponível em GET /Delivery/ByAuthId (Conciliar e recuperar entregas).

Quem expira o quê

Você define os dois prazos na requisição (reserveTimeOut na reserva, authTimeOut na autorização) e recebe o resultado por callback (reason 2 ou 6).

Use os prazos da próxima seção como limite de espera.

Suas esperas e o que fazer quando estouram

Os prazos abaixo são sugestões de partida; combine o prazo de espera na homologação.

Cancelar com Delivery/Stop

É a única rota de cancelamento, para reserva ou autorização que você não vai usar.

Um corpo sem nenhum dos dois campos responde 400. Depois da autorização, envie os dois. Os dois precisam formar um par (o authId é da autorização desse reserveId).

POST /Delivery/Stop
SecretKeyAuthorization: <SUA_CHAVE>
Content-Type: application/json

{
  "reserveId": "b8f2c6e4-1a3d-4f5b-8c7e-9d0a2b4c6e8f",
  "authId": "c3a9e1f7-5d2b-4c8a-b6e4-0f1d3a5c7e9b"
}

Resposta 201

{
  "cancelId": "e5d7a1b3-9c2f-4a68-8b1e-3c4d5e6f7a8b"
}

O que acontece depois

O 201 só confirma que a ConectTec recebeu o pedido e o encaminhou ao concentrador do posto. O resultado chega pelo callback de status:

• reason 3, 7 ou 8: o cancelamento foi concluído. Trate os três como o mesmo resultado.
• reason 9 ou 14: o cancelamento não se completou. A reserva ou a autorização continua ativa e expira sozinha no prazo (reserveTimeOut ou authTimeOut).

Depois de um Stop, a reserva não pode mais ser autorizada: a tentativa responde 500, ou 400 depois que o callback de encerramento chega. Se o cliente mudar de ideia, faça uma nova reserva. O ponto de abastecimento só aceita essa nova reserva quando a anterior fechar (veja o 406 em Reservar o ponto de abastecimento), o que acontece quando o callback de encerramento chega.

Se o abastecimento já começou, o Stop pede ao concentrador que pare a bomba. A parada é confirmada pelo callback com reason 8. Se já houve volume, a entrega chega com o volume parcial.

Erros

Repetir um Stop em reserva já fechada responde 201 do mesmo jeito. Formato geral de erros em Erros e diagnóstico.

Passo 5 de 6

Receber a entrega

Quando o abastecimento fecha, a ConectTec envia ao seu servidor o registro final: volume, preço aplicado, total e encerrantes. É o dado que você usa para cobrar.

Quando o callback chega

recebido assíncrono

A ConectTec envia o callback assim que o posto informa o fim do abastecimento, em {base}/FuelPoint/Delivery. Cadastre a base sem barra no final, senão a URL sai com //.

Cada callback é enviado uma vez, no momento do evento. A entrega fica disponível em GET /Delivery/ByAuthId (Conciliar e recuperar entregas).

A entrega e os callbacks de status são enviados à parte. Processe cada callback pelo reason; um estado final não volta atrás, e ignore um reason 0 ou 4 que chegue depois de um estado final. A entrega fecha o abastecimento.

Autentique o callback pelo segmento secreto na base de callback, HTTPS e a conferência do reserveId/authId contra as suas operações. Veja Contrato dos callbacks.

Condições para o callback sair

A ConectTec só envia o callback quando as três condições valem ao mesmo tempo:

1. O abastecimento fechou numa autorização sua, feita com a sua chave, no ponto de abastecimento e no posto vinculados a você. Abastecimento sem autorização sua (por exemplo, o frentista abastece sem passar por você) não gera callback, mesmo no mesmo posto.
2. A base de callback está cadastrada.
3. A rota de entrega está liberada para você. A ConectTec libera rota a rota; peça a de entrega além da de status.

O callback sai para reservas e autorizações suas, com a base cadastrada e a rota liberada. Confirme o cadastro e a liberação com a ConectTec; a entrega também está disponível pelo authId (veja Conciliar e recuperar entregas).

Campos do corpo

O corpo é JSON na raiz, sem envelope, com Content-Type: application/json. Os números chegam sem arredondamento. A tabela usa a caixa exata do JSON, inclusive ETotStart e ETotEnd com E maiúsculo.

• volume * price pode diferir de total: a bomba arredonda e trunca por conta própria. Cobre pelo total.
• volume, price, total ou encerrantes ausentes ou nulos indicam entrega incompleta: consulte-a em Conciliar e recuperar entregas.
• O preço aplicado vem em price, e o de tabela em pricewithoutdiscount. Cobre pelo total da entrega.

Exemplo completo

O exemplo é o abastecimento de 30,00 L de gasolina no ponto de abastecimento 3 do Posto Exemplo, com desconto de R$ 0,20 por litro. A bomba aplicou R$ 6,09 e cobrou R$ 182,70. Sem desconto seriam R$ 6,29 por litro, ou R$ 188,70.

{
  "stationId": 4021,
  "fuelPointNumber": 3,
  "hoseNumber": 1,
  "reserveId": "b8f2c6e4-1a3d-4f5b-8c7e-9d0a2b4c6e8f",
  "authId": "c3a9e1f7-5d2b-4c8a-b6e4-0f1d3a5c7e9b",
  "deliveryId": 98765432,
  "dateTime": "2026-11-03T14:22:05-03:00",
  "volume": 30.0,
  "price": 6.09,
  "total": 182.7,
  "pricewithoutdiscount": 6.29,
  "ETotStart": 125430.50,
  "ETotEnd": 125460.50,
  "fuel": { "fuelType": 5, "name": "Gasolina Comum" },
  "tank": {
    "name": "TQ 01",
    "number": 1,
    "fuel": { "fuelType": 5, "name": "Gasolina Comum" }
  },
  "attendant": { "id": 0, "name": null, "tag": "" },
  "customer": { "id": 0, "name": null, "tag": null, "odometer": 0 }
}

Casar com a sua autorização e deduplicar

A entrega se identifica pela combinação abaixo.

O deliveryId é o mesmo no callback e na consulta por authId (conciliação), mas a chave de deduplicação é a dupla acima. Na consulta, o encerrante vem como eTotEnd (minúsculo).

Para conferir o preço, compare price com cada preço que você enviou para o bico, em todos os níveis (veja Troca de preço e desconto). Se bater com algum, o desconto foi aplicado. Se não bater com nenhum, a cobrança saiu pela tabela (também vale quando a confirmação da reserva trouxe hoseNumber [0] e você autorizou no preço de tabela): cobre o total da entrega. pricewithoutdiscount vale quando for maior que 0.

Entrega com authId que você não reconhece: não crie cobrança.

Depois de cobrar o total e encerrar a reserva, informe o pagamento.

Responder em menos de 5 segundos

Responda HTTP 200, exatamente esse código, em menos de 5 segundos. Só o 200 conta como recebido: 201, 202 e 204 não contam, redirecionamentos não são seguidos e o corpo da resposta não é lido. O certificado TLS do seu servidor precisa ser válido. Cada callback é enviado uma vez; responda 200 mesmo para uma entrega que você não reconhece.

Entrega tardia

Quando o posto perde a conexão no meio do abastecimento, o concentrador guarda a entrega e a envia quando a conexão volta, com o dateTime do abastecimento e o ETotEnd correto. O combustível foi entregue: cobre pelo total mesmo que a sua reserva ou autorização já tenha expirado do seu lado. Até a conexão do posto voltar, a entrega ainda não está na ConectTec: sem callback e sem registro na consulta significa "ainda não".

Entrega que não chegou

Siga a estratégia de Conciliar e recuperar entregas.

1. Consulte pelo authId. A consulta devolve a entrega se a ConectTec a recebeu.
2. Se devolver, processe pelo mesmo caminho do callback. A consulta traz eTotStart/eTotEnd em camelCase e priceWithoutDiscount sempre 0: compare price com cada preço que você autorizou. Detalhes em Conciliar e recuperar entregas.
3. Se não devolver, a entrega ainda não está disponível (entrega tardia, veja acima). Repita conforme a estratégia e, se persistir, acione a ConectTec com stationId, fuelPointNumber, reserveId e authId.

O formato de todos os callbacks e a defesa do endpoint estão em Contrato dos callbacks.

Passo 6 de 6

Informar o pagamento

Depois que o abastecimento termina, avise a ConectTec se o cliente pagou e se o posto precisa emitir nota. É uma chamada síncrona: o 200 já significa que o informe foi recebido.

Para que serve e quando chamar

POST /V3/Delivery/TransactionStatus informa o resultado do pagamento de um abastecimento que já aconteceu, mais os dados fiscais quando houver nota. A ConectTec encaminha a informação ao posto, para conciliar o caixa e emitir nota fiscal. A chamada não mexe na bomba, não altera a autorização e não confirma o abastecimento: isso é o callback de entrega.

Chame depois de receber a entrega, com o total dela em value. Antes disso a ConectTec pode responder 404.

Antes de repetir um POST, confira o estado da operação anterior. Cada chamada vale como novo informe, repassado ao posto, e o último prevalece. Chame uma vez por mudança de estado do pagamento.

Requisição

Cabeçalhos: SecretKeyAuthorization com a sua chave (veja Credenciais e ambiente) e Content-Type: application/json. Os nomes de campo não diferenciam maiúsculas de minúsculas e campos desconhecidos são ignorados, mas as enumerações só aceitam número: "paid" no lugar de 1 resulta em 400.

Campos principais

Campos opcionais

Dados fiscais do destinatário

Todos opcionais. Envie quando invoiceType for 0 ou 2 e o posto precisar dos dados do destinatário na nota.

Estados do pagamento

O campo transactionStatus aceita estes valores. A ConectTec aceita qualquer valor de 0 a 4; a sequência é responsabilidade do seu sistema.

Pagamento que falha depois do abastecimento. O tratamento de um abastecimento não pago é regra contratual entre você, a ConectTec e o posto. Abra o caso com a ConectTec, com authId, reserveId e o motivo.

Para 0, 3 e 4, combine o uso com a ConectTec no cadastro.

Nota fiscal

O campo invoiceType diz ao posto o que emitir para este abastecimento.

Valor pago

O value é o total pago por esta transação, em reais. A ConectTec o compara com o total do abastecimento:

Envie value com no máximo duas casas decimais, igual ao total da entrega (R$ 182,70 no exemplo, 182.70 no JSON). Para valor maior que o total, combine com a ConectTec; só faz sentido se o cliente pagou outros itens na mesma transação.

Exemplos

Abastecimento de referência do guia: 30,00 L de gasolina a R$ 6,09, total de R$ 182,70.

Pago, sem nota fiscal:

POST /V3/Delivery/TransactionStatus
SecretKeyAuthorization: <SUA_CHAVE>
Content-Type: application/json

{
  "reserveId": "b8f2c6e4-1a3d-4f5b-8c7e-9d0a2b4c6e8f",
  "authId": "c3a9e1f7-5d2b-4c8a-b6e4-0f1d3a5c7e9b",
  "providerStationID": 4021,
  "operationalDate": "2026-11-03T14:22:05-03:00",
  "transactionStatus": 1,
  "invoiceType": 3,
  "value": 182.70
}

Contestado, para uma cobrança Pix do mesmo abastecimento que expirou sem pagamento: os mesmos dados, com transactionStatus 3 e operationalDate 2026-11-03T14:52:05-03:00.

{
  "reserveId": "b8f2c6e4-1a3d-4f5b-8c7e-9d0a2b4c6e8f",
  "authId": "c3a9e1f7-5d2b-4c8a-b6e4-0f1d3a5c7e9b",
  "providerStationID": 4021,
  "operationalDate": "2026-11-03T14:22:05-03:00",
  "transactionStatus": 1,
  "invoiceType": 0,
  "value": 182.70,
  "customerIdentification": "11222333000181",
  "paymentReconciliationId": "E00000000202611031722aBcDeFgHiJk",
  "invoiceFreeText": "Abastecimento realizado por aplicativo",
  "razaoSocial": "Empresa Exemplo Ltda",
  "inscricaoEstadual": "123456789",
  "logradouro": "Avenida Exemplo",
  "enderecoNumero": "1000",
  "bairro": "Centro",
  "cidade": "São Paulo",
  "uf": "SP",
  "cep": "01001000",
  "codigoIbge": "3550308"
}

Resposta

Resposta 200, corpo vazio. O 200 significa que o informe foi recebido. Se a chamada falhar por rede ou tempo esgotado, confira o estado da operação anterior antes de repetir, uma única vez e com o mesmo corpo. Cada 200 avisa o posto de novo.

Erros

Decida pelo status HTTP. O corpo pode variar e não é contrato.

Sequência típica por meio de pagamento

A primeira chamada só é aceita depois que a entrega existe na ConectTec: callback recebido ou entrega recuperada pela conciliação.

Conciliar e recuperar entregas

A consulta por authId devolve a entrega que a ConectTec registrou, tenha o callback chegado ou não.

Por que conciliar

• Envio único. Cada callback é enviado uma vez, no momento do evento. A entrega fica disponível em GET /Delivery/ByAuthId.
• Entrega tardia. Se o posto perde a conexão no meio do abastecimento, o concentrador guarda a entrega e a envia quando a conexão volta, com o dateTime do abastecimento. Veja Entrega tardia.
• Condições do callback. O callback sai para reservas e autorizações suas, com a base cadastrada e a rota liberada. Veja Condições para o callback sair.

A consulta cobre a entrega. O estado da reserva chega pelos callbacks de status.

Consultar por authId

síncrono

Devolve a entrega que consumiu uma autorização sua, se a ConectTec a recebeu do posto. Serve para qualquer entrega, tenha o callback chegado ou não. Use a chave de API em SecretKeyAuthorization (veja Credenciais e ambiente); a estratégia de quando chamar está em Estratégia recomendada.

Parâmetro

Exemplo de requisição

GET /Delivery/ByAuthId?authId=c3a9e1f7-5d2b-4c8a-b6e4-0f1d3a5c7e9b
SecretKeyAuthorization: <SUA_CHAVE>

Resposta

Status 200 com um objeto delivery. A tabela lista os campos que você usa.

{
  "delivery": {
    "stationId": 4021,
    "fuelPointId": 17,
    "hoseNumber": 1,
    "authId": "c3a9e1f7-5d2b-4c8a-b6e4-0f1d3a5c7e9b",
    "reserveId": "b8f2c6e4-1a3d-4f5b-8c7e-9d0a2b4c6e8f",
    "deliveryId": 98765432,
    "dateTime": "2026-11-03T14:22:05",
    "volume": 30.0,
    "price": 6.09,
    "priceWithoutDiscount": 0.0,
    "total": 182.7,
    "fuel": { "name": "Gasolina Comum", "imagePath": null, "fuelType": 5, "fuelTypeDescription": "gasolina" },
    "tank": {
      "number": 1,
      "name": "TQ 01",
      "volume": 0.0,
      "tcVolume": 0.0,
      "ullage": 0.0,
      "temperature": 0.0,
      "waterLevel": 0.0,
      "fuel": { "name": "Gasolina Comum", "imagePath": null, "fuelType": 5, "fuelTypeDescription": "gasolina" }
    },
    "attendant": { "tag": "", "name": "", "id": 0 },
    "customer": { "tag": "", "name": "", "id": 0, "odometer": 0 },
    "eTotStart": 125430.50,
    "eTotEnd": 125460.50
  }
}

Erros

Decida pelo status HTTP.

Com o 200, processe a entrega como se fosse o callback e informe o pagamento, como em Casar com a sua autorização e deduplicar.

Diferenças entre callback e consulta

A entrega recuperada tem o mesmo conteúdo do callback, com estas diferenças.

Estratégia recomendada

Um job seu consulta as autorizações que continuam sem entrega.

1. Primeira consulta 15 minutos depois da autorização. Antes disso o 404 é esperado.
2. Espaçamento. A cada 15 minutos nas primeiras 2 horas, depois de hora em hora, até 48 horas depois da autorização. Combine o limite de requisições no cadastro.
3. Com 200, processe pelo mesmo caminho do callback. Com 404, agende a próxima tentativa.
4. Passadas as 48 horas, abra um caso com a ConectTec com stationId, fuelPointNumber, reserveId, authId e hora, volume, total e bico esperados, para conferir se há entrega gravada sem vínculo. Se a entrega chegar depois, ingira normalmente.

Saem da fila de espera as autorizações que terminaram sem nenhum litro abastecido: callback de status com reason 3 (reserva cancelada), 5 (autorização recusada), 6 (autorização expirada) ou 7 (autorização cancelada antes de abastecer). Continuam na fila, até o fim da janela, as que receberam reason 13 (interrompido) ou reason 8 (parada durante o abastecimento), porque pode haver volume parcial e a entrega ainda chega. Veja Máquinas de estado. Se aparecer entrega para uma autorização que saiu da fila, ingira normalmente.

Deduplicação com o callback

O mesmo abastecimento pode chegar por callback e por ByAuthId, em qualquer ordem.

• Chave. authId (minúsculas) + ETotEnd com 3 casas decimais. Se ETotEnd vier nulo ou 0, use authId + dateTime sem o sufixo de fuso (-03:00). Compare os GUIDs como recebidos (a ConectTec os envia em minúsculas).
• Quem chegou primeiro vale. A segunda cópia é descartada, mas se a consulta gravou primeiro, atualize pricewithoutdiscount na linha existente com o valor do callback, que a consulta não traz. Sobrescreva só quando for maior que 0.

Como tratar cada resultado

Erros comuns a todas as rotas: Erros e diagnóstico. Formato do callback: Receber a entrega.

Contrato dos callbacks

Os dois endereços que a ConectTec chama no seu servidor, o que responder, como casar cada callback com o seu estado e o corpo do callback de status.

O que a ConectTec chama

Você informa uma base de callback no cadastro, por exemplo https://integracao.suaempresa.com.br/conecttec/8f3k2m9q, sem barra no final. A ConectTec acrescenta o caminho de cada callback.

Método POST, corpo JSON na raiz, sem envelope, em camelCase (exceções do callback de entrega em Receber a entrega). O cabeçalho é Content-Type: application/json; a autenticação é pelo segmento secreto da base (Segurança do endpoint). Ignore campos que você não conhece.

Regras de resposta

1. Responda exatamente HTTP 200, em menos de 5 segundos. O corpo da resposta é ignorado. 201, 202, 204 e redirecionamentos (301, 302) não contam como recebido: cadastre a base já em HTTPS.
2. Cada callback é enviado uma vez, no momento do evento. Timeout, erro de conexão, certificado inválido, 4xx e 5xx contam como não recebido. O certificado TLS precisa ser público e válido: certificado autoassinado é recusado.
3. Responda 200 também ao que você não reconhece: reason reservado, campo novo, reserva desconhecida (o callback pode chegar antes de você gravar a reserva).
4. Ordem. Processe cada callback pelo reason; um estado final não volta atrás, e ignore um reason 0 ou 4 que chegue depois de um estado final.

Chave de cada callback

O corpo traz dados pessoais (customer.name, customer.tag, attendant.name): guarde o corpo cru com acesso restrito e prazo de retenção definido.

Segurança do endpoint

1. Segmento secreto no caminho. Cadastre a base com um trecho aleatório de pelo menos 128 bits, como https://integracao.suaempresa.com.br/conecttec/8f3k2m9q (os exemplos do guia usam um valor curto). Para trocá-lo, peça à ConectTec que cadastre uma base nova e aceite as duas durante a troca.
2. Confira os identificadores. Confirme que reserveId ou authId existe entre as suas operações e que stationId e fuelPointNumber batem. GUIDs: guarde e compare exatamente como recebidos (a ConectTec envia em minúsculas).
3. O que dispara cobrança é uma entrega que casa com uma autorização sua, conferida contra o que você enviou. Nunca um callback de status.

Testar o seu servidor

Envie ao seu endpoint, no caminho /V3/FuelPoint/Status, o corpo de Autorização aceita, e no caminho /FuelPoint/Delivery o corpo de Receber a entrega. O esperado é HTTP 200 nas duas.

Corpo do callback de status

Todos os campos abaixo estão sempre presentes no JSON, mas vários trazem um valor neutro quando não se aplicam (null, 0 ou [0]). O nome do campo respeita a caixa do JSON.

Como ler o campo price

• No reason 0 (reserva aceita), price é a tabela de preços do ponto de abastecimento: price[nível][posição], com uma linha por nível (a linha 0 é o nível 1, até 4 níveis) e uma coluna por entrada de hoseNumber. Com hoseNumber igual a [1, 2] e price igual a [[6.29, 4.39], [6.19, 4.29]], o bico 1 custa 6,29 no nível 1 e 6,19 no nível 2. A leitura completa está em Reservar o ponto de abastecimento.
• Depois da autorização, o preço aplicado é o price da entrega. O preço aplicado e o valor a cobrar estão nos campos price, pricewithoutdiscount e total do callback de entrega.

Quais valores chegam

Em operação normal, o reason que chega a você é um destes: 0 a 9 e 11 a 14. O significado e o que fazer em cada um estão em O que chegou e o que fazer, e a tabela completa de reason e fuelPointStatus está em Enumerações e limites. O fim do abastecimento não chega por este callback: ele chega pela entrega.

Exemplos por momento

Os quatro corpos abaixo seguem o abastecimento de exemplo: ponto de abastecimento 3 do posto 4021, gasolina no bico 1 e etanol no bico 2, 30,00 L de gasolina a R$ 6,09. Os objetos customer e attendant vêm com valores neutros nestes exemplos.

{
  "stationId": 4021,
  "fuelPointNumber": 3,
  "hoseNumber": [1, 2],
  "reserveId": "b8f2c6e4-1a3d-4f5b-8c7e-9d0a2b4c6e8f",
  "authId": null,
  "fuelPointStatus": 1,
  "reason": 0,
  "volume": 0.0,
  "total": 0.0,
  "fuel": { "fuelType": 0, "name": null },
  "tank": { "number": 1, "name": "TQ 01", "fuel": { "fuelType": 0, "name": null } },
  "customer": { "tag": null, "name": null, "id": 0, "odometer": 0 },
  "attendant": { "tag": null, "name": null, "id": 0 },
  "price": [[6.29, 4.39], [6.19, 4.29]]
}

{
  "stationId": 4021,
  "fuelPointNumber": 3,
  "hoseNumber": [1],
  "reserveId": "b8f2c6e4-1a3d-4f5b-8c7e-9d0a2b4c6e8f",
  "authId": "c3a9e1f7-5d2b-4c8a-b6e4-0f1d3a5c7e9b",
  "fuelPointStatus": 2,
  "reason": 4,
  "volume": 0.0,
  "total": 0.0,
  "fuel": { "fuelType": 5, "name": "Gasolina Comum" },
  "tank": { "number": null, "name": null, "fuel": { "fuelType": 5, "name": "Gasolina Comum" } },
  "customer": { "tag": null, "name": null, "id": 0, "odometer": 0 },
  "attendant": { "tag": null, "name": null, "id": 0 },
  "price": [[6.09]]
}

{
  "stationId": 4021,
  "fuelPointNumber": 3,
  "hoseNumber": [1],
  "reserveId": "b8f2c6e4-1a3d-4f5b-8c7e-9d0a2b4c6e8f",
  "authId": "c3a9e1f7-5d2b-4c8a-b6e4-0f1d3a5c7e9b",
  "fuelPointStatus": 4,
  "reason": 11,
  "volume": 12.4,
  "total": 75.52,
  "fuel": { "fuelType": 5, "name": "Gasolina Comum" },
  "tank": { "number": 1, "name": "TQ 01", "fuel": { "fuelType": 5, "name": "Gasolina Comum" } },
  "customer": { "tag": null, "name": null, "id": 0, "odometer": 0 },
  "attendant": { "tag": null, "name": null, "id": 0 },
  "price": [[6.09]]
}

{
  "stationId": 4021,
  "fuelPointNumber": 3,
  "hoseNumber": [1, 2],
  "reserveId": "b8f2c6e4-1a3d-4f5b-8c7e-9d0a2b4c6e8f",
  "authId": null,
  "fuelPointStatus": 1,
  "reason": 2,
  "volume": 0.0,
  "total": 0.0,
  "fuel": { "fuelType": 0, "name": null },
  "tank": { "number": 1, "name": "TQ 01", "fuel": { "fuelType": 0, "name": null } },
  "customer": { "tag": null, "name": null, "id": 0, "odometer": 0 },
  "attendant": { "tag": null, "name": null, "id": 0 },
  "price": [[6.29, 4.39], [6.19, 4.29]]
}

Máquinas de estado

Três máquinas: o ciclo do abastecimento, o estado do ponto de abastecimento (o visor da bomba) e o estado do pagamento. Cada uma traz o sinal exato que você recebe em cada transição.

Como modelar

O estado da reserva chega pelos callbacks de status e de entrega. Cada callback é enviado uma vez, no momento do evento. O seu sistema monta o estado a partir de quatro sinais:

• A resposta HTTP das suas chamadas. O 201 da reserva e o 201 da autorização só confirmam o recebimento. O 406 da reserva diz que o ponto de abastecimento está em uso.
• O callback de status (POST {base de callback}/V3/FuelPoint/Status), com reason e fuelPointStatus. Decida primeiro pelo reason.
• O callback de entrega (POST {base de callback}/FuelPoint/Delivery). É o único aviso de que o abastecimento terminou.
• O seu relógio. Em alguns caminhos o sinal é o prazo vencido. Esperas sugeridas em Suas esperas.

Regras para a sua máquina:

• Todo callback traz o reserveId; o authId aparece depois da autorização.
• Processe cada callback pelo reason; um estado final não volta atrás, e ignore um reason 0 ou 4 que chegue depois de um estado final.
• A confirmação pode chegar antes de você gravar a resposta do 201. Responda 200 e reprocesse em alguns segundos.
• Um reason ou fuelPointStatus fora das tabelas desta seção é reservado: não muda o estado. Responda 200 (veja Contrato dos callbacks).
• Garanta o valor do cliente (pré-autorização, saldo ou pagamento) antes de autorizar e use-o como limitValue. Ajuste a cobrança pelo total da entrega. Se a autorização falhar ou expirar, desfaça a garantia.

Ciclo do abastecimento

Estados

Transições

Os estados finais não voltam: um callback atrasado que os contradiga, como um reason 0 depois de reserva expirada ou de Sem confirmação, é ignorado. O Stop também é aceito em Reserva pedida e Autorização pedida, e o resultado só aparece quando o posto confirma. Entregue encerra esta máquina; o pagamento tem a sua, mais abaixo.

Reservar com ponto de abastecimento ocupado

O 406 só acontece na reserva e quer dizer que nenhuma reserva nova foi criada. O ponto de abastecimento libera quando a reserva anterior fecha, ou em até reserveTimeOut + 120 s desde a criação dela (180 s com reserveTimeOut 60). Algumas tentativas a cada poucos segundos não esgotam essa espera. Se o cliente é o mesmo e você tem o reserveId, retome a reserva aberta. Para 500, timeout, 502, 503 e 504, veja Erros da reserva.

POST /V4/Delivery/Reserve
SecretKeyAuthorization: <SUA_CHAVE>
Content-Type: application/json

{
  "stationId": 4021,
  "fuelPointNumber": 3,
  "providerId": "<SEU_PROVIDER_ID>",
  "reserveTimeOut": 60
}

A resposta 201 está em Reservar o ponto de abastecimento.

Tabela de reason

O reason diz o que aconteceu com a reserva ou a autorização. Estes são todos os valores que a ConectTec envia e documenta. Qualquer outro valor é reservado: não mude o estado, ignore o conteúdo e responda 200.

Os fins de reserva e de autorização são os reason 1, 2, 3, 5, 6, 7, 8, 12 e 13. Nenhum outro encerra nada.

Estado do ponto de abastecimento

O campo fuelPointStatus do callback de status diz como o ponto de abastecimento está naquele instante. Ele complementa o reason: um reason de encerramento vale mesmo quando o status diz outra coisa. Só chega callback enquanto existe uma reserva ou autorização sua no ponto de abastecimento.

O campo vai de 0 a 6, mas você só recebe 0 a 4. Os valores 5 e 6 não são enviados. Decida sempre primeiro pelo reason.

Transições

A sequência abaixo é a de uma bomba em operação normal. Processe cada callback pelo estado que ele traz.

O status 0 não encerra nada: espere o próximo callback ou o fim do prazo da etapa em curso. O status 3 não muda a máquina do abastecimento.

Estado do pagamento (TransactionStatus)

Depois da entrega, você informa o resultado do pagamento com POST /V3/Delivery/TransactionStatus (Informar o pagamento). Vale o último valor enviado, em qualquer ordem. Cada chamada avisa o posto de novo, inclusive repetir o mesmo valor.

Campos, nota fiscal e erros estão em Informar o pagamento. Combine o uso de 3 e 4 com a ConectTec no cadastro.

Erros e diagnóstico

Todos os erros da API por rota, as regras que valem para qualquer erro e um roteiro de verificação para os sete problemas que mais travam uma integração.

Regras gerais

1. Decida pelo status HTTP. Vale o status, não o corpo.
2. O 201 só confirma o recebimento. Reserva, autorização e Stop respondem 201 quando a ConectTec recebe o pedido; o resultado vem pelo callback de status. Veja Acompanhar e cancelar.
3. O 401 cobre várias causas. Chave errada, rota não liberada, identificador de outro integrador e, no mapa de pista e no QR code, posto não vinculado respondem 401, em geral sem corpo. QR code inexistente responde 401. Veja Entender o 401.
4. O 500 tem duas famílias. Dado inválido seu (providerId fora do formato GUID, reserveId inexistente, fuelType ou hoseNumber que o ponto de abastecimento não tem, reserva com Stop pendente) ou erro ao processar.
5. Erros de validação não passam com repetição. Exceções: o 404 de ByAuthId e de TransactionStatus (abastecimento ainda não registrado) e o 400 da autorização com reserva ainda sem reason 0.
6. Status fora das tabelas (415, 502, 503, 504, falha de conexão) segue a linha de 5xx e timeout abaixo.

Antes de repetir um POST, confira o estado da operação anterior. Depois de timeout ou 5xx:

Erros por rota

Consolidam as tabelas de cada seção; o detalhe de cada causa está na seção da rota.

GET /QRCodeInformation/{codigo}

Detalhes em Erros do QR code.

GET /V6/ForecourtMap/ById/{stationId}

Detalhes em Erros do mapa de pista.

POST /V4/Delivery/Reserve

Detalhes em Erros da reserva.

POST /V2/Delivery/AuthorizeByFuelType e POST /V2/Delivery/Authorize

POST /Delivery/Stop

Detalhes em Cancelar com Delivery/Stop.

POST /V3/Delivery/TransactionStatus

Detalhes em Erros do pagamento.

GET /Delivery/ByAuthId

Suas respostas aos callbacks

Responda HTTP 200, exatamente esse código, em menos de 5 segundos, mesmo para um evento que você não reconhece. Qualquer outro código, inclusive 201 e 204, e qualquer demora acima do limite não contam como recebido. Cada callback é enviado uma vez, no momento do evento; o corpo da resposta não é lido. Veja Responder em menos de 5 segundos.

Diagnóstico por sintoma

Passos em ordem, do mais barato ao mais caro. O último de cada roteiro diz quando acionar a ConectTec; os dados a enviar estão em Quando acionar a ConectTec.

Recebo 401 em tudo

1. Header. O nome é SecretKeyAuthorization e o valor é a chave crua, sem Bearer.
2. Mapa de pista do posto de testes. GET /V6/ForecourtMap/ById/{stationId} com o stationId do cadastro. Com 200, chave e posto estão certos e o problema é outro (passo 4). Com 401, a chave está errada, o stationId não é o do cadastro ou a rota não foi liberada. Na homologação, qualquer posto que não seja o de testes responde 401.
3. Mapa 200 e outra rota 401: a rota não foi liberada para o seu cadastro. Confira Rotas.
4. Chamada com identificadores: reserveId e authId precisam ter sido devolvidos às suas próprias chamadas; na reserva, o providerId do corpo precisa ser o dono da chave.
5. Acione a ConectTec com a rota completa, o stationId, o status e o horário da chamada com fuso.

A reserva retorna 201 mas a confirmação não chega

Três causas dão o mesmo sintoma: posto sem comunicação, ponto de abastecimento que não responde ao concentrador e callback que não chega ao seu servidor.

1. Prazo. Dentro do reserveTimeOut enviado, o callback de confirmação é esperado. Veja Suas esperas.
2. Outro reason. 1, 2, 3 ou 12 encerram a reserva; veja Confirmação pelo callback de status. O reason 1 pode vir com qualquer status.
3. Seu endpoint. Se o callback chegou à borda e a aplicação não o processou, confira que o reserveId é comparado como recebido (minúsculas) e que ele já estava gravado: o callback pode chegar milissegundos depois do 201. Teste o endpoint como em O callback não chega no meu servidor.
4. stationStatus. O stationStatus indica se o concentrador do posto está conectado; a disponibilidade do ponto de abastecimento vem na resposta da reserva. Veja stationStatus.
5. Venceu o prazo sem callback: envie POST /Delivery/Stop com o reserveId e ignore qualquer reason 0 posterior. Só reserve o mesmo ponto de abastecimento depois do Stop confirmado ou da janela do 406. Veja Se a confirmação não chegar.
6. Acione a ConectTec se repetir com stationStatus: true e endpoint respondendo 200. Se nenhum callback de nenhum posto chega, peça a verificação da base de callback e da liberação da rota de status.

Recebo 406 ao reservar

O 406 indica reserva aberta sua no mesmo ponto de abastecimento. Ponto de abastecimento ocupado por outro motivo não gera 406: a recusa, se houver, chega pelo callback de status.

1. Procure no seu sistema uma reserva sua nesse ponto de abastecimento sem entrega e sem reason de encerramento. Se for do mesmo cliente, reutilize o reserveId.
2. Se não vai mais ser usada, envie Stop e espere reason 3, 7 ou 8. A reserva fecha também quando o abastecimento é gravado ou chega reason 1, 2, 5, 6, 12 ou 13.
3. Sem o reserveId, espere a janela: a reserva se libera em reserveTimeOut + 120 s contados da criação (240 s no pior caso, com reserveTimeOut 120). Um reserveTimeOut menor encurta a janela.
4. Acione a ConectTec se o 406 persistir depois de reserveTimeOut + 120 s da última reserva.

O callback não chega no meu servidor

Vale para o status do ponto de abastecimento ({base de callback}/V3/FuelPoint/Status) e para a entrega concluída ({base de callback}/FuelPoint/Delivery). O callback sai para reservas e autorizações suas, com a base cadastrada e a rota liberada.

1. Condições de envio. Status só sai para reservas e autorizações suas; ponto de abastecimento ocioso não gera callback; fuelPointStatus 5 e 6 não saem, salvo junto de reason 1. A entrega só sai para abastecimento com autorização sua. Veja Condições para o callback sair.
2. Seu endpoint. Envie de fora da sua rede o payload de reason 0 de Testar o seu servidor, em POST {base}/V3/FuelPoint/Status. O esperado é HTTP 200 em menos de 5 s.
3. Caminho. A ConectTec acrescenta o caminho de cada callback à base cadastrada. Com a base https://integracao.suaempresa.com.br/conecttec/8f3k2m9q, o status chega em /conecttec/8f3k2m9q/V3/FuelPoint/Status e a entrega em /conecttec/8f3k2m9q/FuelPoint/Delivery. Cadastre a base sem barra no final, para não ficar //.
4. Resposta. Só o HTTP 200 conta; 201, 204, redirecionamento e demora acima de 5 s não contam como recebido. O corpo da resposta não é lido.
5. TLS e origem. Certificado válido com cadeia completa; autoassinado ou expirado faz o envio falhar. Autentique pelo caminho secreto, não por IP de origem.
6. Envio. Cada callback é enviado uma vez, no momento do evento. A entrega fica disponível em GET /Delivery/ByAuthId (A entrega não chegou). O estado seguinte chega no próximo callback; a entrega fecha o abastecimento.
7. Acione a ConectTec se o endpoint responde 200 no teste e nenhuma operação elegível gera callback. Peça a verificação da base cadastrada e da liberação das rotas de status e de entrega.

A entrega não chegou

A consulta GET /Delivery/ByAuthId?authId={authId} mostra se a entrega já está registrada.

1. Espere alguns minutos. Se o posto perde a conexão no meio do abastecimento, o concentrador guarda a entrega e a envia quando a conexão volta, com o dateTime do abastecimento. Veja Entrega tardia.
2. Confirme que houve abastecimento com autorização sua. Abastecimento feito sem passar por você não gera callback para o seu servidor.
3. Consulte pelo authId. Com 200, a entrega está disponível para conciliar. Para receber o callback, siga o diagnóstico do callback e confira a base cadastrada e a liberação da rota de entrega.
4. Com 404, a ConectTec ainda não recebeu o registro do posto. Repita no ritmo da estratégia de conciliação.
5. Acione a ConectTec se seguir 404 até o fim do prazo da estratégia. Se tiver, envie o volume e o valor que o cliente viu na bomba.

Na resposta da consulta, os campos ficam dentro de delivery, a chave é eTotStart/eTotEnd (no callback é ETotStart/ETotEnd), priceWithoutDiscount vem 0 e dateTime é a hora local do posto. Para confrontar desconto, use o preço de tabela do callback de reserva que você guardou. Veja Conferir o preço cobrado na entrega.

O desconto não foi aplicado na bomba

O preço aplicado vem em price da entrega, e o de tabela em pricewithoutdiscount.

1. Confirme na entrega, não no status. Compare price do callback de entrega com o enviado e com o de tabela. Em 6,09 contra 6,29, o desconto de R$ 0,20 foi aplicado; igual à tabela, a bomba não aplicou. O preço aplicado é o price da entrega. Veja Conferir o preço cobrado na entrega.
2. Ponto de abastecimento sem troca de preço. Com fuelPoint.configPrice false, a bomba pode cobrar pela tabela. Veja Quando a troca de preço não vale.
3. Combustível. Em AuthorizeByFuelType, GNV (fuelType 15) em ponto de abastecimento sem preset ignora preço e limite.
4. O que você enviou. Compare o corpo da autorização com A matriz de preço da autorização. Se a confirmação da reserva veio com hoseNumber [0], autorize sem desconto e cobre pelo price da entrega.
5. Tratamento com o cliente em Se a bomba não aplicou o desconto.
6. Acione a ConectTec se repetir no mesmo posto ou bico com configPrice: true.

Recebo 404 no TransactionStatus

O abastecimento citado ainda não está registrado.

1. Entrega ainda não recebida. O registro só existe depois da entrega; informar o pagamento antes dela costuma responder 404. Se ela não chegou, consulte GET /Delivery/ByAuthId (A entrega não chegou).
2. Par de identificadores. reserveId e authId precisam ser da mesma autorização: envie os dois que vieram juntos no callback de entrega. Um authId que não é seu responde 401.
3. Acione a ConectTec se o 404 persistir com a entrega consultável por ByAuthId.

Quando acionar a ConectTec

Depois do roteiro do sintoma. A ConectTec localiza o caso pelos dados abaixo.

Enumerações e limites

Todos os códigos numéricos da API e dos callbacks em um lugar só, mais os prazos, as faixas e os formatos que fazem uma chamada ser aceita ou recusada.

Todas as enumerações trafegam como número, exceto limitType, que é a string "$" ou "V". Os nomes das tabelas não aparecem no JSON (exceto fuelTypeDescription, informativa). Um número fora das tabelas é valor reservado: ignore e, em callback, responda 200.

Tipo de combustível (fuelType)

Aparece no mapa de pista, na resposta da reserva, nos callbacks de status e de entrega (dentro de fuel e tank.fuel), na consulta por authId, e é um campo que você envia em Autorizar por tipo de combustível. Os valores vão de 0 a 16.

• O texto fuelTypeDescription vem vazio ("") quando o número não está na tabela, e o campo só existe no mapa, na reserva e na consulta por authId. Os callbacks trazem apenas fuelType e name.
• O name é o nome que o posto deu ao combustível ("Gasolina Comum") e pode variar de posto para posto. A chave é fuelType.
• Na autorização por tipo, campo ausente vale 0 (Outra) e valores acima de 16 respondem 500.

"hoses": [
  {
    "hoseNumber": 1,
    "price": 6.29, "price2": 6.19, "price3": 0, "price4": 0,
    "fuel": { "name": "Gasolina Comum", "imagePath": null, "fuelType": 5, "fuelTypeDescription": "gasolina" }
  },
  {
    "hoseNumber": 2,
    "price": 4.39, "price2": 4.29, "price3": 0, "price4": 0,
    "fuel": { "name": "Etanol", "imagePath": null, "fuelType": 1, "fuelTypeDescription": "etanol" }
  }
]

Estado do ponto de abastecimento (fuelPointStatus)

Vem no callback de status e diz o que o ponto de abastecimento (o visor da bomba) está fazendo naquele instante. O callback sai para reservas e autorizações suas, com a base cadastrada e a rota liberada.

Os valores 5 e 6 existem no posto, mas a ConectTec não os envia por este callback, a não ser junto de um reason 1. O fim do abastecimento chega somente pelo callback de entrega.

O reason diz o que aconteceu, e o fuelPointStatus diz como o ponto de abastecimento está. Quando os dois parecem discordar, vale o reason. Detalhes de uso em Acompanhar e cancelar e em Máquinas de estado.

Motivo do callback de status (reason)

Estes são os valores com significado definido. A coluna "Encerra" diz se o reason fecha a reserva ou a autorização: depois de um valor que encerra, aquela reserva não aceita mais autorização, e o ponto de abastecimento deixa de dar 406 por causa dela (veja Erros da reserva).

Tipo de limite (limitType)

Campo da autorização. É uma string de exatamente 1 caractere, sem espaço e com a caixa da tabela.

Envie limitType e limitValue sempre juntos, com "$" ou "V". O limitValue aceita 1 ou mais; zero e negativos dão 400, e mais de duas casas decimais são arredondadas para duas. Em GNV sem preset, não envie nenhum dos dois (Caso GNV). As escolhas por situação estão em Limite do abastecimento.

Estado do pagamento (transactionStatus)

Campo do informe de pagamento. Aceita de 0 a 4, só como número (o texto "paid" dá 400). O valor é repassado ao posto, e os estados podem ser enviados em qualquer ordem.

Quando usar cada um, e o que combinar com a ConectTec para 0, 3 e 4, está em Estados do pagamento.

Documento fiscal (invoiceType)

Campo do informe de pagamento. Diz ao posto o que emitir. Aceita de 0 a 3.

Campos com formato diferente no status e na entrega

Alguns campos têm o mesmo nome nos dois callbacks e formatos diferentes. Leia cada callback com o seu próprio modelo.

Os campos completos estão em Contrato dos callbacks e em Campos do corpo da entrega.

Tempos e limites

"Sugerido" marca recomendação do guia; a API não impõe.

Prazos e janelas

Formatos e faixas de campos

Homologação e entrada em produção

O roteiro de testes que você roda no posto de testes antes de a ConectTec vincular postos reais: 14 casos com o que fazer e o que esperar, os critérios de aprovação e o que muda em produção.

Como a homologação funciona

Não há ambiente separado. Você testa em https://api.conecttec.com.br, a mesma URL de produção, com a chave restrita a um posto de testes. A ConectTec informa o stationId dele no cadastro (veja Ambiente único e homologação no posto de testes). Cada chamada chega a um concentrador de verdade: uma reserva ocupa o ponto de abastecimento e uma autorização libera a bomba.

1. Combine a janela de testes com a ConectTec.
2. Rode os 14 casos e guarde as evidências.
3. Envie as evidências pelo contato técnico do cadastro e peça a aprovação. Combine com a ConectTec o prazo de revisão e o prazo para vincular os postos reais.
4. A ConectTec vincula os postos reais ao seu cadastro e informa o stationId de cada um.

Pré-requisitos

Rode os casos em sequência. Antes de cada caso que reserva, o ponto de abastecimento precisa estar livre: encerre a reserva anterior com Stop ou espere o callback de encerramento (reason 1, 2, 3, 5, 6, 7, 8, 12 ou 13). Sem isso a nova reserva responde 406, por até reserveTimeOut mais 120 segundos. Antes de começar, resolva:

Checklist dos casos obrigatórios

A aprovação exige os 14.

• Caso 1. Autenticação: chave válida responde 200, chave errada, sem chave e posto alheio respondem 401.
• Caso 2. Mapa de pista: pontos de abastecimento, bicos, tipos de combustível, preset, configPrice e stationStatus lidos.
• Caso 3. QR code: código do ponto de abastecimento vira stationId e fuelPointNumber; código inválido responde 401.
• Caso 4. Reserva com confirmação: 201 com reserveId, depois callback reason 0 com a matriz de preço, que se lê pela posição de hoseNumber.
• Caso 5. Reserva expirada: callback reason 2, autorização depois dele responde 400, nova reserva é aceita.
• Caso 6. Ponto de abastecimento ocupado: segunda reserva no mesmo ponto de abastecimento responde 406.
• Caso 7. Cancelamento por Stop: 201, callback reason 3 ou 8, reserva descartada, sem nova autorização sobre ela.
• Caso 8. Autorização por combustível com desconto: 201 com authId, callback reason 4.
• Caso 9. Autorização por bico: 201, callback reason 4, bico certo na entrega.
• Caso 10. Abastecimento completo: acompanhamento, entrega recebida e preço conferido contra o que você enviou.
• Caso 11. Autorização expirada sem abastecer: callback reason 6, nenhuma entrega, nova reserva aceita.
• Caso 12. Callback que você não reconhece: responde 200 e não muda nenhuma reserva.
• Caso 13. Servidor fora do ar: a entrega é recuperada por Delivery/ByAuthId.
• Caso 14. TransactionStatus: pago (1) responde 200; autorização expirada, sem abastecimento, responde 404.

Os casos, um a um

Os exemplos usam o Posto Exemplo (stationId 4021), o ponto de abastecimento 3 com o bico 1 de gasolina comum (fuelType 5) e o bico 2 de etanol (fuelType 1). No posto de testes, use os números, preços e identificadores dele.

Caso 1. Autenticação

Faça. GET /V6/ForecourtMap/ById/4021 com a sua chave (mapa de pista). Repita com a chave alterada, sem o cabeçalho e com outro stationId.

Esperado.

• Chave válida e posto de testes: HTTP 200 com o objeto station.
• Chave alterada, cabeçalho ausente e stationId que não é o seu: HTTP 401 nos três casos (Autenticar uma chamada).

Caso 2. Mapa de pista

Faça. Na resposta do caso 1, leia pontos de abastecimento, bicos, stationStatus, preset e configPrice. Campos em Campos do mapa de pista.

Esperado.

• No ponto de abastecimento 3 do exemplo, o bico 1 tem fuelType 5 e o bico 2 tem fuelType 1.
• stationStatus é true. Se for false, o concentrador do posto de testes está sem conexão: avise a ConectTec antes de seguir.
• O preço da autorização vem da reserva (Preço do mapa e preço da reserva).

Caso 3. QR code

Faça. GET /QRCodeInformation/0004217 com o qrcode do ponto de abastecimento 3 no mapa, e depois com um código de 7 dígitos que não exista.

Esperado.

• HTTP 200 com {"fuelPointNumber": 3, "stationId": 4021}.
• Código que não existe: HTTP 401. Código com menos de 7 caracteres: HTTP 400.

Detalhes em Consultar um QR code.

Caso 4. Reserva com confirmação

Faça. POST /V4/Delivery/Reserve no ponto de abastecimento 3 com reserveTimeOut 60 (requisição). Termine com Stop ou espere o reason 2, para o ponto de abastecimento ficar livre para o caso seguinte.

Esperado.

• HTTP 201 com reserveId e o objeto fuelPoint.
• Callback POST {base}/V3/FuelPoint/Status com o mesmo reserveId e reason 0.
• price é lido pela posição em hoseNumber, não pelo número do bico (Como ler a matriz de preço). No exemplo, o bico 1 dá 6,29 no nível 1 e 6,19 no nível 2. Se hoseNumber vier [0], autorize sem desconto, no preço de tabela; o preço aplicado é o price da entrega.
• O callback pode chegar poucos milissegundos depois do 201. A autorização só vale depois do reason 0.

Se o reason 0 não chegar até o fim do reserveTimeOut, a causa mais comum é a base de callback. Veja a tabela Se um caso falhar.

Caso 5. Reserva expirada

Faça. Reserve o ponto de abastecimento com reserveTimeOut 10, espere o reason 0 e não autorize. Depois do callback reason 2, tente autorizar a mesma reserva e faça uma nova reserva no ponto de abastecimento.

Esperado.

• Callback com o mesmo reserveId e reason 2 (reserveTimedOut) logo depois dos 10 segundos.
• POST /V2/Delivery/AuthorizeByFuelType nessa reserva responde HTTP 400.
• A nova reserva no mesmo ponto de abastecimento responde 201.
• Se um reason 0 atrasado chegar depois do reason 2, ignore-o (Quando a reserva expira).

Caso 6. Ponto de abastecimento ocupado (406)

Faça. Reserve o ponto de abastecimento 3 com reserveTimeOut 60, espere o reason 0 e envie uma segunda reserva para o mesmo ponto de abastecimento antes de o prazo acabar. Depois cancele a primeira (caso 7) ou espere que expire.

Esperado.

• A segunda reserva responde HTTP 406 e não gera reserveId novo. A primeira reserva segue ativa, sem alteração.
• Uma reserva aberta bloqueia o ponto de abastecimento por até reserveTimeOut mais 120 segundos, e a janela fecha antes se chegar um callback de encerramento (Erros da reserva).

Caso 7. Cancelamento por Stop

Faça. Reserve o ponto de abastecimento, espere o reason 0 e envie POST /Delivery/Stop só com o reserveId (antes da autorização; depois dela, reserveId e authId). Depois tente autorizar a reserva.

Esperado.

• HTTP 201 com cancelId. O 201 só confirma o recebimento.
• Callback com reason 3 ou 8. Os dois indicam cancelamento concluído. Se vier reason 9 ou 14, o cancelamento não se completou e a reserva expira sozinha no prazo.
• Autorizar a reserva cancelada responde HTTP 500 até o callback de encerramento chegar e HTTP 400 depois dele (Cancelar com Delivery/Stop).
• Uma nova reserva no ponto de abastecimento só é aceita depois do callback de encerramento. Antes dele, o 406 do caso 6 volta.

Caso 8. Autorização por combustível, com desconto

Faça. Reserve o ponto de abastecimento 3, espere o reason 0 e chame POST /V2/Delivery/AuthorizeByFuelType com fuelType 5, updateRate 2, authTimeOut 120 e desconto de R$ 0,20 por litro nos dois níveis (price [[6.09], [5.99]]). Envie limitType "$" e limitValue. Requisição completa em Autorizar por tipo de combustível. Esta autorização é a mesma do caso 10 e expira em authTimeOut segundos (reason 6) depois do reason 4. Se o operador precisar de mais tempo, use authTimeOut 200, o máximo, e comece o caso 10 logo em seguida.

Esperado.

• HTTP 201 com authId e o mesmo reserveId.
• Callback com reason 4 e o authId preenchido.
• O preço aplicado vem em price da entrega, conferido no caso 10 (O campo price).
• Opcional: depois do reason 4, autorizar a mesma reserva de novo responde 400.

Caso 9. Autorização por bico

Faça. Reserve de novo e chame POST /V2/Delivery/Authorize com hoseNumber [2] (etanol), price [[4.29], [4.19]] (desconto de R$ 0,10 por litro) e authTimeOut 120 (Autorizar por bico), um bico só. Com alguém na bomba, abasteça uns litros para ver o bico na entrega. Sem ninguém, envie Stop com reserveId e authId depois do reason 4 e espere o callback reason 7 ou 8. Se o ponto de abastecimento de testes tem um bico só, rode o caso com ele.

Esperado.

• HTTP 201 com authId, depois callback com reason 4.
• Se houve abastecimento, a entrega traz hoseNumber 2 e fuel.fuelType 1, e price igual a um dos preços enviados para o bico 2 (4,29 ou 4,19 no exemplo).
• Bico que o ponto de abastecimento não tem responde 500.

Caso 10. Abastecimento completo, entrega e preço

Exige alguém na bomba. Faça. Com a autorização do caso 8 em reason 4 e dentro do authTimeOut dela (a expiração é definitiva), o operador tira o bico, abastece gasolina e devolve o bico.

Esperado.

• Callback com fuelPointStatus 4 quando o abastecimento começa (em geral com reason 11; não exija o reason), depois callbacks de andamento com volume e total crescentes, a cada updateRate segundos aproximadamente.
• O fim do abastecimento chega pelo callback POST {base}/FuelPoint/Delivery, com o seu authId e o seu reserveId.
• Conferência do preço: price é um dos preços com desconto que você enviou, um por nível (6,09 ou 5,99 no exemplo), e pricewithoutdiscount é o de tabela (6,29). No exemplo do guia, 30,00 L a 6,09 dão total 182,70 com desconto e 188,70 sem. price igual a pricewithoutdiscount indica que a bomba não aplicou a troca de preço (configPrice, níveis enviados). Veja Troca de preço e desconto.
• total é 182,70 se a bomba aplicou 6,09, e ETotEnd menos ETotStart fica próximo de volume. Cobre pelo total da entrega, não por volume vezes price.
• O servidor respondeu 200 em menos de 5 segundos (Casar com a sua autorização e deduplicar).

Caso 11. Autorização expirada sem abastecer

Faça. Reserve o ponto de abastecimento, espere o reason 0, autorize com authTimeOut 20 e não tire o bico do descanso. Depois do prazo, tente autorizar de novo e faça uma nova reserva. O authId é usado no caso 14.

Esperado.

• Callback reason 4 e, cerca de 20 segundos depois, callback reason 6 (authTimedOut). A expiração é definitiva.
• Nenhum callback de entrega chega para esse authId.
• Nova autorização na mesma reserva responde 400.
• Se um reason 4 atrasado chegar depois do reason 6, ignore-o (Se ninguém abastecer).

Caso 12. Callback que você não reconhece

Faça. Envie ao seu servidor o corpo da entrega do caso 10 (POST {base}/FuelPoint/Delivery, payload em Exemplo completo) com um authId que você não criou, e um callback de status com reason 99.

Esperado.

• As duas chamadas respondem HTTP 200.
• O authId que você não criou é gravado como entrega órfã, sem cobrança, e a resposta continua 200.
• Um callback de status com reason que o guia não lista (por exemplo, 99) recebe 200 e não muda o estado de nenhuma reserva (Regras de resposta).

Caso 13. Servidor fora do ar e recuperação por conciliação

Exige alguém na bomba. Faça.

1. Reserve e autorize um novo abastecimento e espere o reason 4.
2. Tire o seu servidor de callback do ar (ou faça-o devolver 503) antes de o operador abastecer.
3. O operador abastece e devolve o bico. Cada callback é enviado uma vez, no momento do evento.
4. Suba o servidor de novo e consulte GET /Delivery/ByAuthId?authId=... (Consultar por authId).

Esperado.

• A consulta responde HTTP 200 com a entrega. Com 404, a entrega ainda não está disponível (estratégia de consulta).
• O formato da consulta difere do callback (Diferenças entre callback e consulta). Na consulta priceWithoutDiscount vem 0; o preço aplicado é o price.
• O estado seguinte chega no próximo callback; a entrega fecha o abastecimento.

Caso 14. TransactionStatus: pago e abastecimento inexistente

Faça. Com a entrega do caso 10, chame POST /V3/Delivery/TransactionStatus com transactionStatus 1, value igual ao total da entrega e invoiceType 3 para o posto não emitir nota. Depois informe o pagamento do authId expirado do caso 11 (Informar o pagamento).

Esperado.

• Pago: HTTP 200 com corpo vazio. O último estado enviado prevalece.
• O authId da autorização expirada responde HTTP 404, porque não houve entrega.
• Para usar 0, 3 ou 4, combine o uso com a ConectTec no cadastro.

Se um caso falhar

Evidências para a aprovação

Envie à ConectTec, pelo contato técnico do cadastro, uma tabela com uma linha por caso:

• Número do caso e data e hora em que você o rodou.
• O reserveId e o authId usados.
• O status HTTP de cada chamada e o reason de cada callback recebido, com a hora de recebimento.
• Para o caso 10: price, pricewithoutdiscount, volume e total da entrega e o valor que você cobrou.
• Para o caso 13: a entrega recuperada gravada uma vez só, pela chave authId e ETotEnd.

Critérios para entrar em produção

A ConectTec vincula postos reais quando estes pontos estão atendidos.

• Os 14 casos do roteiro passaram e as evidências foram enviadas à ConectTec.
• O servidor de callback responde 200 em menos de 5 segundos, com HTTPS e certificado válido.
• A entrega é deduplicada por authId mais ETotEnd com 3 casas (ou authId mais dateTime sem fuso, se ETotEnd vier nulo ou 0) e cobrada pelo total da entrega.
• O job de conciliação periódico está implantado e ligado desde o primeiro dia em produção.
• Recomendado: o TransactionStatus é enviado com valor igual ao total, uma vez por abastecimento. Combine com a ConectTec se a chamada é obrigatória para o seu cadastro.

O que muda em produção

A URL, a chave, o providerId e a base de callback continuam os mesmos. O que muda:

Suporte

Fale com a ConectTec pelo contato técnico informado no cadastro, que a ConectTec também usa para avisar sobre incidentes. Envie:

• stationId e fuelPointNumber.
• reserveId e authId, quando existirem.
• Método e rota da chamada, status HTTP recebido e horário com fuso (2026-11-03T14:22:05-03:00).
• Para callback que não chegou: a base de callback cadastrada, o horário esperado e o que o log do seu servidor mostra.

Erros por rota: Erros e diagnóstico. reason e estados do ponto de abastecimento: Máquinas de estado.

Versão do guia 1.0, novembro de 2026.