← HomeFleetPay / Schema

OperacaoCiot

Structure preserved from the versioned API contract.

Technical descriptions are translated from the versioned contract. Original identifiers and JSON are preserved; data examples are omitted.

idstring · uuidRequired

The operation's public address. Created before contacting the provider, so it exists even when the declaration is rejected — precisely when a CIOT number never came into existence.

referencia_externastring | nullOptional

statusstringRequired

registered is the only state that authorizes the trip to proceed. sent means the declaration was submitted without a final outcome — query it before any retry. pending means the declaration has not even been transmitted.

"pending" · "sent" · "registered" · "error" · "cancelled" · "closed"

numerostring | nullOptional

The CIOT. null until ANTT returns it, and permanently if ANTT rejects it.

codigo_verificadorstring | nullOptional

protocolostring | nullOptional

mensagemstring | nullOptional

Provider response or rejection reason.

tipo_operacaostringOptional

"lotacao" · "fracionado"

declarado_emstring | null · date-timeOptional

registrado_emstring | null · date-timeOptional

When the CIOT was registered with ANTT. null until it exists.

cteobject | nullOptional

The CT-e linked to the operation, if any. null is the normal case for this route — the field is always included, even when null, to answer explicitly whether the operation is linked to a CT-e.

Original JSON Definition (Portuguese Descriptions)

{
  "type": "object",
  "required": [
    "id",
    "status"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "O endereço público da operação. Nasce **antes** da chamada ao provedor, e por isso\nexiste mesmo quando a declaração é recusada — é o caso em que o número do CIOT\nnunca chegou a existir.\n"
    },
    "referencia_externa": {
      "type": [
        "string",
        "null"
      ]
    },
    "status": {
      "type": "string",
      "enum": [
        "pending",
        "sent",
        "registered",
        "error",
        "cancelled",
        "closed"
      ],
      "description": "`registered` é o único que autoriza seguir viagem. `sent` é declaração entregue sem\nveredito — consulte antes de qualquer nova tentativa. `pending` é declaração que\nnem foi transmitida.\n"
    },
    "numero": {
      "type": [
        "string",
        "null"
      ],
      "description": "O CIOT. `null` até a ANTT devolver — e para sempre, se ela recusar."
    },
    "codigo_verificador": {
      "type": [
        "string",
        "null"
      ]
    },
    "protocolo": {
      "type": [
        "string",
        "null"
      ]
    },
    "mensagem": {
      "type": [
        "string",
        "null"
      ],
      "description": "O que o provedor respondeu, ou o motivo da recusa."
    },
    "tipo_operacao": {
      "type": "string",
      "enum": [
        "lotacao",
        "fracionado"
      ]
    },
    "declarado_em": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "registrado_em": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "Quando o CIOT passou a existir na ANTT. `null` enquanto não existir."
    },
    "cte": {
      "type": [
        "object",
        "null"
      ],
      "description": "O CT-e ao qual a operação está amarrada, quando houver. **`null` é o caso normal\ndesta rota** — o campo viaja sempre, mesmo nulo, para que a pergunta \"isto está\namarrado a um CT-e?\" tenha resposta explícita.\n",
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid"
        }
      }
    }
  }
}