Modulo Transportadora - Contrato de API Backend

Este documento descreve o contrato esperado pelo frontend para o modulo de Transportadora.

1) Visao geral

Base path dos endpoints: /transportadora
Content-Type: application/json
Autenticacao (modo real): sessao via cookie (withCredentials=true no client)
Modo mock (VITE_AUTH_MODE=mock): o frontend envia header x-mock-response-name para rotear respostas mockadas

2) Parametros comuns de listagem

Os endpoints de lista recebem, quando aplicavel:

page (number, opcional)
per_page (number, opcional)
search (string, opcional)

Exemplo de query:

GET /transportadora/faturas?page=1&per_page=8&search=23019

3) Formato padrao das respostas

3.1 Listas

{
	"data": [],
	"meta": {
		"current_page": 1,
		"from": 1,
		"last_page": 1,
		"per_page": 8,
		"to": 8,
		"total": 8
	}
}

Campos de meta esperados pelo frontend:

current_page: number
from: number | null
last_page: number
per_page: number
to: number | null
total: number

3.2 Detalhe

{
	"data": {}
}

3.3 Acao de cancelamento

{
	"message": "Contestacao cancelada com sucesso.",
	"data": {}
}

4) Enums e regras de dominio

4.1 Produto

CIOT
FRETE_DIGITAL

4.2 Status de fatura

PAGO
PENDENTE
VENCIDO

4.3 Status de lancamento

PROCESSADO
EM_ANALISE
CONTESTADO

4.4 Status de contestacao

ABERTA
EM_ANALISE
CANCELADA

4.5 Regras importantes

Campos monetarios devem ser number (nao string formatada).
Datas sao string.
cte pode ser null.
lancamento_uuid pode ser null.
contestacao_pendente e opcional em lancamentos.
Para recurso nao encontrado em detalhe/cancelamento, backend deve retornar 404.

5) Endpoints

5.1 GET `/transportadora/faturas`

Retorna lista de faturas da transportadora.

Request (cURL)

curl -X GET "{{BASE_URL}}/transportadora/faturas?page=1&per_page=8&search=23019" \
  -H "Content-Type: application/json"

Response 200 (exemplo)

{
	"data": [
		{
			"id_fatura": 23019,
			"uuid": "fat-transp-23019",
			"data_faturamento": "2026-04-16",
			"data_vencimento": "2026-04-24",
			"valor_total": 45200,
			"valor_total_pago": 0,
			"data_recebimento": null,
			"saldo": 45200,
			"status_fatura_transportadora": "PENDENTE",
			"postos": [
				{
					"posto_nome": "Posto Horizonte",
					"docs": [
						{
							"lancamento_uuid": "lanc-transp-002",
							"numero_doc": "FD-10382",
							"tipo_doc": "Frete Digital",
							"data_lancamento": "2026-04-16 10:10",
							"valor_sem_taxa": 5400,
							"valor_da_taxa": 180,
							"valor_liquido": 5220
						}
					]
				}
			]
		}
	],
	"meta": {
		"current_page": 1,
		"from": 1,
		"last_page": 1,
		"per_page": 8,
		"to": 1,
		"total": 1
	}
}

Campos do item `data[]`

id_fatura: number
uuid: string
data_faturamento: string
data_vencimento: string
valor_total: number
valor_total_pago: number
data_recebimento: string | null
saldo: number
status_fatura_transportadora: "PAGO" | "PENDENTE" | "VENCIDO"
postos: PostoDetalhe[]

PostoDetalhe:

posto_nome: string
docs: PostoDetalheDoc[]

PostoDetalheDoc:

lancamento_uuid?: string | null
numero_doc: string
tipo_doc: string
data_lancamento: string
valor_sem_taxa: number
valor_da_taxa: number
valor_liquido: number

5.2 GET `/transportadora/lancamentos`

Retorna lista de lancamentos (CIOT e FRETE_DIGITAL).

Request (cURL)

curl -X GET "{{BASE_URL}}/transportadora/lancamentos?page=1&per_page=8&search=CIOT-240014" \
  -H "Content-Type: application/json"

Response 200 (exemplo)

{
	"data": [
		{
			"id": 1,
			"uuid": "lanc-transp-001",
			"data_lancamento": "2026-04-16 08:30",
			"ciot": "CIOT-240014",
			"cte": null,
			"contratado": "Transvale Logistica",
			"origem": "Cuiaba/MT",
			"destino": "Goiania/GO",
			"valor": 18250,
			"valor_gerado": 25100,
			"produto": "CIOT",
			"situacao": "PROCESSADO",
			"posto_nome": "Posto Horizonte",
			"motorista": "Carlos Mendes"
		},
		{
			"id": 3,
			"uuid": "lanc-transp-003",
			"data_lancamento": "2026-04-17 14:45",
			"ciot": "FD-88401",
			"cte": "35260419472743521672570010008840111000088401",
			"contratado": "Rota Brasil",
			"origem": "Lucas do Rio Verde/MT",
			"destino": "Santos/SP",
			"valor": 22300,
			"valor_gerado": 48000,
			"produto": "FRETE_DIGITAL",
			"situacao": "CONTESTADO",
			"posto_nome": "Auto Posto Imperial",
			"motorista": "Patricia Nunes",
			"contestacao_pendente": true
		}
	],
	"meta": {
		"current_page": 1,
		"from": 1,
		"last_page": 1,
		"per_page": 8,
		"to": 2,
		"total": 2
	}
}

Campos do item `data[]`

id: number
uuid: string
data_lancamento: string
ciot: string
cte: string | null
contratado: string
origem: string
destino: string
valor: number
valor_gerado: number
produto: "CIOT" | "FRETE_DIGITAL"
situacao: "PROCESSADO" | "EM_ANALISE" | "CONTESTADO"
posto_nome: string
motorista: string
contestacao_pendente?: boolean

5.3 GET `/transportadora/lancamentos/{uuid}`

Retorna o detalhe de um lancamento.

Request (cURL)

curl -X GET "{{BASE_URL}}/transportadora/lancamentos/lanc-transp-003" \
  -H "Content-Type: application/json"

Response 200 (exemplo)

{
	"data": {
		"id": 3,
		"uuid": "lanc-transp-003",
		"data_lancamento": "2026-04-17 14:45",
		"ciot": "FD-88401",
		"cte": "35260419472743521672570010008840111000088401",
		"contratado": "Rota Brasil",
		"origem": "Lucas do Rio Verde/MT",
		"destino": "Santos/SP",
		"valor": 22300,
		"valor_gerado": 48000,
		"produto": "FRETE_DIGITAL",
		"situacao": "CONTESTADO",
		"posto_nome": "Auto Posto Imperial",
		"motorista": "Patricia Nunes",
		"contestacao_pendente": true
	}
}

Response 404 (nao encontrado)

{
	"message": "Lancamento nao encontrado"
}

Observacao: o frontend trata 404 como retorno nulo para esse fluxo.

5.4 GET `/transportadora/postos`

Retorna lista de postos vinculados a transportadora.

Request (cURL)

curl -X GET "{{BASE_URL}}/transportadora/postos?page=1&per_page=8&search=Cuiaba" \
  -H "Content-Type: application/json"

Response 200 (exemplo)

{
	"data": [
		{
			"uuid": "posto-transp-001",
			"cnpj": "12654321000190",
			"nome_fantasia": "Posto Horizonte",
			"cidade": "Cuiaba",
			"estado": "MT",
			"produto": "CIOT",
			"localizacao": "BR-364, km 121",
			"latitude": -15.5961,
			"longitude": -56.0967
		}
	],
	"meta": {
		"current_page": 1,
		"from": 1,
		"last_page": 1,
		"per_page": 8,
		"to": 1,
		"total": 1
	}
}

Campos do item `data[]`

uuid: string
cnpj: string
nome_fantasia: string
cidade: string
estado: string
produto: "CIOT" | "FRETE_DIGITAL"
localizacao: string
latitude: number
longitude: number

5.5 GET `/transportadora/contestacoes`

Retorna lista de contestacoes.

Request (cURL)

curl -X GET "{{BASE_URL}}/transportadora/contestacoes?page=1&per_page=8&search=FD-88401" \
  -H "Content-Type: application/json"

Response 200 (exemplo)

{
	"data": [
		{
			"uuid": "contest-transp-001",
			"lancamento_uuid": "lanc-transp-003",
			"data": "2026-04-18 09:10",
			"fatura": "23019",
			"documento": "FD-88401",
			"valor_desconto": 780,
			"motivo": "Taxa divergente",
			"produto": "FRETE_DIGITAL",
			"status": "ABERTA",
			"historico": [
				{
					"data": "2026-04-18 09:10",
					"usuario": "Patricia Nunes",
					"acao": "Abertura",
					"descricao": "Contestacao aberta pela transportadora"
				},
				{
					"data": "2026-04-18 10:05",
					"usuario": "Controladoria",
					"acao": "Triagem",
					"descricao": "Contestacao enviada para analise financeira"
				}
			]
		}
	],
	"meta": {
		"current_page": 1,
		"from": 1,
		"last_page": 1,
		"per_page": 8,
		"to": 1,
		"total": 1
	}
}

Campos do item `data[]`

uuid: string
lancamento_uuid: string | null
data: string
fatura: string
documento: string
valor_desconto: number
motivo: string
produto: "CIOT" | "FRETE_DIGITAL"
status: "ABERTA" | "EM_ANALISE" | "CANCELADA"
historico: ContestacaoHistoricoItem[]

ContestacaoHistoricoItem:

data: string
usuario: string
acao: string
descricao: string

5.6 POST `/transportadora/contestacoes/{uuid}/cancelar`

Cancela uma contestacao.

Request (cURL)

curl -X POST "{{BASE_URL}}/transportadora/contestacoes/contest-transp-001/cancelar" \
  -H "Content-Type: application/json" \
  -d "{}"

Body esperado

{}

Response 200 (exemplo)

{
	"message": "Contestacao cancelada com sucesso.",
	"data": {
		"uuid": "contest-transp-001",
		"lancamento_uuid": "lanc-transp-003",
		"data": "2026-04-18 09:10",
		"fatura": "23019",
		"documento": "FD-88401",
		"valor_desconto": 780,
		"motivo": "Taxa divergente",
		"produto": "FRETE_DIGITAL",
		"status": "CANCELADA",
		"historico": [
			{
				"data": "2026-04-18 09:10",
				"usuario": "Patricia Nunes",
				"acao": "Abertura",
				"descricao": "Contestacao aberta pela transportadora"
			},
			{
				"data": "2026-04-18 10:05",
				"usuario": "Controladoria",
				"acao": "Triagem",
				"descricao": "Contestacao enviada para analise financeira"
			},
			{
				"data": "2026-04-18 11:40",
				"usuario": "Patricia Nunes",
				"acao": "Cancelamento",
				"descricao": "Contestacao cancelada pela transportadora"
			}
		]
	}
}

Response 404 (nao encontrado)

{
	"message": "Contestacao nao encontrada"
}

Observacao: o frontend trata 404 como retorno nulo para esse fluxo.

6) Padrao de erros recomendado

O frontend funciona com qualquer corpo de erro, mas recomenda-se padrao unico para facilitar troubleshooting:

{
	"message": "Descricao curta do erro",
	"errors": {
		"campo": ["mensagem de validacao"]
	}
}

Status sugeridos:

400 parametros invalidos
401 nao autenticado
403 sem permissao
404 recurso nao encontrado
422 erro de validacao
500 erro interno

Modulo Transportadora - Contrato de API Backend

1) Visao geral

2) Parametros comuns de listagem

3) Formato padrao das respostas

3.1 Listas

3.2 Detalhe

3.3 Acao de cancelamento

4) Enums e regras de dominio

4.1 Produto

4.2 Status de fatura

4.3 Status de lancamento

4.4 Status de contestacao

4.5 Regras importantes

5) Endpoints

5.1 GET /transportadora/faturas

Request (cURL)

Response 200 (exemplo)

Campos do item data[]

5.2 GET /transportadora/lancamentos

Request (cURL)

Response 200 (exemplo)

Campos do item data[]

5.3 GET /transportadora/lancamentos/{uuid}

Request (cURL)

Response 200 (exemplo)

Response 404 (nao encontrado)

5.4 GET /transportadora/postos

Request (cURL)

Response 200 (exemplo)

Campos do item data[]

5.5 GET /transportadora/contestacoes

Request (cURL)

Response 200 (exemplo)

Campos do item data[]

5.6 POST /transportadora/contestacoes/{uuid}/cancelar

Request (cURL)

Body esperado

Response 200 (exemplo)

Response 404 (nao encontrado)

6) Padrao de erros recomendado

5.1 GET `/transportadora/faturas`

Campos do item `data[]`

5.2 GET `/transportadora/lancamentos`

Campos do item `data[]`

5.3 GET `/transportadora/lancamentos/{uuid}`

5.4 GET `/transportadora/postos`

Campos do item `data[]`

5.5 GET `/transportadora/contestacoes`

Campos do item `data[]`

5.6 POST `/transportadora/contestacoes/{uuid}/cancelar`