← HomeFleetPay / API

Synchronize operation CT-e issuance status

Parameters, data structure and responses from the versioned contract.

POST/embarcador/solicitacoes-transporte/{id}/fiscal/sincronizar
sincronizarFiscalSolicitacaoTransporteEmbarcadorSandbox Base: https://api.fleetpay.site/v1

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

Synchronizes the request's tax state (fiscal_status) with an authorized CteDraft belonging to the responsible Aggregated Carrier, validating issuer, tax environment (tp_amb), linkage to the request's operation/NF-e and canonical SEFAZ evidence (sefaz_protocol / cstat = 100 / authorized_at / status = authorized). On cte_timeout, retrying requires canonical evidence of prior SEFAZ status query on the CteDraft (never a client-supplied boolean).

Authentication

Required Scope
operacao — Operations
Module
Direct Contracting (Shipper)
Target Profiles
Shipper · Transport Manager · Dedicated Fleet Contractor
Schemes
OAuth2 client_credentials (POST /oauth/token) or API Key via Authorization: Bearer / X-Api-Key
[
  {
    "oauth2": []
  },
  {
    "chaveApi": []
  }
]
Availability depends on the environment, enabled scopes and provider. This reference does not execute requests or collect credentials.

Parameters

idpath · stringRequired
Constraints
{
  "type": "string"
}

Request Body

Required

application/json

cte_draft_idinteger | nullOptional

ID of the CteDraft linked to the operation and issued by the responsible Aggregated Carrier.

fiscal_statusstring | nullOptional
"ready_for_cte" · "ready_for_cte_prefill" · "cte_prefilled" · "cte_issuing" · "cte_authorized" · "cte_rejected" · "cte_timeout" · null
outcomestring | nullOptional
"ready_for_cte" · "issuing" · "cte_issuing" · "authorized" · "cte_authorized" · "rejected" · "cte_rejected" · "timeout" · "cte_timeout" · null
expected_tp_ambinteger | nullOptional

Expected SEFAZ tax environment (1 = production, 2 = sandbox).

1 · 2 · null

Responses

200 HTTP Response

Fiscal state synchronized with canonical evidence

application/json

successbooleanOptional
commercial_resolutionobject | nullOptional
404 HTTP Response

Request not found

application/json

errorobjectOptional
422 HTTP Response

Tax document not found, belongs to another company/operation, incompatible tax environment or missing canonical SEFAZ evidence

application/json

errorobjectOptional
Complete Operation Definition
{
  "tags": [
    "Solicitações e Contratação de Transporte (Embarcador)"
  ],
  "summary": "Sincronizar situação de emissão de CT-e da operação",
  "description": "Sincroniza o estado fiscal (`fiscal_status`) da solicitação com um `CteDraft` autorizado pertencente ao Transportador Agregado responsável pela operação, validando emitente, ambiente fiscal (`tp_amb`), vínculo com a operação/NF-e da solicitação e evidência canônica SEFAZ (`sefaz_protocol` / `cstat = 100` / `authorized_at` / `status = authorized`). Em caso de `cte_timeout`, nova tentativa exige evidência canônica de consulta prévia de status SEFAZ no `CteDraft` (nunca um booleano enviado pelo cliente).\n",
  "operationId": "sincronizarFiscalSolicitacaoTransporteEmbarcador",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      }
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "cte_draft_id": {
              "type": [
                "integer",
                "null"
              ],
              "description": "ID do `CteDraft` vinculado à operação e emitido pelo Transportador Agregado responsável."
            },
            "fiscal_status": {
              "type": [
                "string",
                "null"
              ],
              "enum": [
                "ready_for_cte",
                "ready_for_cte_prefill",
                "cte_prefilled",
                "cte_issuing",
                "cte_authorized",
                "cte_rejected",
                "cte_timeout",
                null
              ]
            },
            "outcome": {
              "type": [
                "string",
                "null"
              ],
              "enum": [
                "ready_for_cte",
                "issuing",
                "cte_issuing",
                "authorized",
                "cte_authorized",
                "rejected",
                "cte_rejected",
                "timeout",
                "cte_timeout",
                null
              ]
            },
            "expected_tp_amb": {
              "type": [
                "integer",
                "null"
              ],
              "enum": [
                1,
                2,
                null
              ],
              "description": "Ambiente fiscal SEFAZ esperado (`1` = produção, `2` = homologação)."
            }
          }
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Estado fiscal sincronizado com evidência canônica",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/SolicitacaoTransporteResponse"
          }
        }
      }
    },
    "404": {
      "description": "Solicitação não encontrada",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Erro"
          }
        }
      }
    },
    "422": {
      "description": "Documento fiscal inexistente, de outra empresa/operação, ambiente fiscal incompatível ou sem evidência canônica SEFAZ",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Erro"
          }
        }
      }
    }
  },
  "x-fleetpay-scope": "operacao",
  "x-fleetpay-module": "contratacao-direta",
  "x-fleetpay-profiles": [
    "embarcador",
    "gestor",
    "agregado_empresarial"
  ],
  "method": "POST",
  "path": "/embarcador/solicitacoes-transporte/{id}/fiscal/sincronizar"
}