Documenta os detalhes da solicitação na consulta de programadas - #37
Documenta os detalhes da solicitação na consulta de programadas#37Joao-Dutra-Gaudium wants to merge 9 commits into
Conversation
Acrescenta categoria, valor, observação, endereço de origem e a lista de paradas nos exemplos de resposta da consulta de programadas, em corridas e entregas, v1 e v2. Aproveita para corrigir situacao/situacao_formatada no exemplo do v1 de entregas, que estavam invertidos: mostrava o texto em situacao e um datetime em situacao_formatada.
|
✅ Review postada — #37 (review) job_id: |
![gaudinho[bot]](https://avatars.githubusercontent.com/in/3341571?s=60&v=4){kind=small}
There was a problem hiding this comment.
PR de documentação bem executado: os quatro arquivos OpenAPI foram atualizados de forma consistente (JSON válido nos quatro), as entradas de changelog seguem o template do repo com hrefs que existem de fato no docs.json, e a inserção respeita a ordem cronológica decrescente nos dois arquivos. A correção do situacao/situacao_formatada invertidos no v1 de entregas alinha o exemplo com o v1 de corridas — bom aproveitamento. Sugestões abaixo são informativas, nenhuma bloqueia.
As entradas têm added e changed, então pela tabela da etapa 7 da skill de changelog o label é Melhoria (#16A34A), não Novo — mesmo padrão das entradas de 25 jun nos dois arquivos. A nota de corridas dizia que numero_pedido vem vazio, o que não confere: sem pedido vinculado o campo cai no id_externo da própria parada, gravado pelo fluxo do app a partir de id_externo_parada. Nulos de verdade são apenas nome_cliente, telefone_cliente e observacao, cujas colunas legadas não são escritas por nenhum fluxo. Ajusta também o id do exemplo por-id de corridas, que reusava o 1392 da listagem com data, hora e id_mch diferentes.
O teste manual no alfaqa mostrou que a API devolve "Aguardando distribuição"
com d minúsculo — é o texto da tradução em messages/pt_br/SolicitacaoProgramada.php
('aguardando_distribuicao' => 'Aguardando distribuição'). O exemplo estava com
maiúscula, divergindo do valor real.
Acompanha a adição do bloco desejado no txmback3. Nos exemplos de corridas o bloco vem preenchido, que é o caso que motivou a mudança; nos de entregas vem nulo, refletindo que só é preenchido quando há retorno.
8918426
Acompanha o ajuste no txmback3. Corrida traz o endereço de destino e paradas só com endereço; entrega traz as paradas com os dados do pedido e não traz destino da solicitação, porque cada destino fica na parada. Ambas ganham o nome do passageiro.
Acompanha o ajuste no txmback3: o campo só faz sentido em corridas, onde o integrador informa quem viaja via dados_passageiro.
A resposta só traz a chave paradas quando há o que listar, então os exemplos com lista vazia documentavam um formato que a API não produz.
|
/gaudinho review |
|
✅ Review postada — #37 (review) job_id: |
There was a problem hiding this comment.
2 blockers de correção documental na nota do changelog de corridas: a afirmação de que paradas some da resposta em corrida direta contradiz o precedente "paradas": [] já documentado em pages/v1/openapi-corridas.json:4277, e a afirmação de que numero_pedido "não existe em corridas" é desmentida pelos próprios exemplos de corridas do repo (v1:4325, v2:2623 e v2:3689) — além de divergir do corpo do PR, que diz que os campos de pedido "saem vazios". Chave ausente vs. chave presente com valor vazio é diferença de contrato que muda o parsing do integrador; confirmar com a implementação do txmback3 antes de publicar.
3 participants
Descrição
Documenta os campos novos que a consulta de programadas passa a devolver:
categoria,valor(
estimadoeprefixado),observacao, endereço de origem (coleta/partida) e a lista deparadas. Em corridas entram aindadesejado(destino do passageiro) enome_passageiro.Estratégia. Os exemplos de resposta foram atualizados nos quatro arquivos OpenAPI — v1 e v2,
corridas e entregas — porque o
consultarProgramadado V1 é compartilhado pelos dois domínios,então a mudança aparece em todos eles.
A resposta varia conforme o tipo de operação, e os exemplos refletem isso: as paradas de
corrida trazem só o endereço, sem
numero_pedido,nome_cliente,telefone_clienteeobservacao— corrida não tem pedido vinculado. As de entrega trazem esses campos.desejadoenome_passageiroaparecem só em corridas, porque em entrega o destino de cada item fica narespectiva parada e não há passageiro. E a chave
paradassó vem quando há alguma: corridadireta não tem nenhuma. As notas dos dois changelogs registram cada uma dessas diferenças.
Entradas de changelog em
changelog.mdx(corridas) echangelog-entregas.mdx(entregas),seguindo o template da skill do repo: seção
addedpara os campos novos echangedpara oid_mch_programada, que a consulta por id passou a devolver.Correção aproveitada. No v1 de entregas,
situacaoesituacao_formatadaestavaminvertidos no exemplo: mostrava o texto (
"Distribuída") emsituacaoe um datetime emsituacao_formatada. O v1 de corridas já estava correto. Corrigido junto por estar no mesmobloco de exemplo.
Escopo. Apenas exemplos de resposta e changelog — nenhum parâmetro de request mudou, e
nenhum campo que já existia deixou de vir: os campos ausentes por tipo de operação são todos
introduzidos pela mesma entrega.
PR relacionado:
txmback3(implementação).Vídeo referência docs:
Gravacao.de.Tela.2026-08-06.as.12.59.20.mov