Integração com o Basama, sistema usado por clientes do PetroW: criação e cancelamento de ordem no formato SisPetro, com regras próprias desse sistema. Autenticação, perfis e erros seguem o manual geral das APIs de terceiro.
Autenticação em todos os exemplos: veja Autenticação. Teste no navegador pelo Swagger ou importe a coleção do Postman.
| Endpoint | Métodos | Para que serve |
|---|---|---|
basama/ordem_create |
POST | Cria ordem no formato SisPetro (integração Basama) |
basama/ordem_cancel |
POST | Cancela ordem pendente no formato SisPetro (Basama) |
Cria ordem no formato SisPetro (integração Basama). Endpoint legado no formato do SisPetro: corpo {ORDEM_CARREGAMENTO:{...}} com nomes em maiúsculas. Monta os compartimentos pelos veículos (placas SEQFROTA a SEQFROTA4; compartimentos numerados em sequência pelos veículos) e cria ordem C (com itens e totais) ou D (um produto: o do último compartimento; quantidade = soma). Recusa WEBNUMEROOCCLIENTE já usado em ordem não cancelada do app. Perfil cliente só cria para o próprio CNPJ (outro = 403); perfil filial cria a ordem na filial do acesso.
/v1/terceiro/basama/ordem_createCria ordem (C ou D) no layout SisPetro
CODTRANSP não é usado: não define a transportadora da ordem.
Perfis: App, Rede, Filial, Cliente, Pessoa
Corpo (JSON objeto)
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
ORDEM_CARREGAMENTO |
object | sim | Objeto raiz com os campos abaixo. |
ORDEM_CARREGAMENTO.CNPJEMPRESA |
string | sim | CNPJ do cliente (congênere) no PetroW. |
ORDEM_CARREGAMENTO.TIPO |
string | sim | C (carregamento) ou D (descarregamento). Outro valor = 400. |
ORDEM_CARREGAMENTO.DATA |
string | sim | dd/mm/aaaa: vira validade_inicial (00:00); validade_final fica sem limite. |
ORDEM_CARREGAMENTO.CODTRANSP |
string | não | Na prática, o CPF do motorista: procura motorista ativo por CPF. Sem CPF válido, usa o motorista da última ordem do veículo 1 ou um motorista padrão do app. |
ORDEM_CARREGAMENTO.SEQFROTA |
string | sim | Placa do veículo 1 (cavalo). |
ORDEM_CARREGAMENTO.SEQFROTACARRETA |
string | não | Placa do veículo 2. |
ORDEM_CARREGAMENTO.SEQFROTATREM |
string | não | Placa do veículo 3. |
ORDEM_CARREGAMENTO.SEQFROTA4 |
string | não | Placa do veículo 4. |
ORDEM_CARREGAMENTO.COLETAAMOSTRA |
string | não | '1' = coleta amostra (amostras = 1 nos itens); outro valor = 0. |
ORDEM_CARREGAMENTO.WEBNUMEROOCCLIENTE |
string | não | Vira codigo_interno. Não pode repetir em ordem não cancelada do app. |
ORDEM_CARREGAMENTO.OBSERVACAO |
string | não | |
ORDEM_CARREGAMENTO.COMPARTIMENTACAO_OC |
array | sim | [{COMPARTIMENTO (texto numérico, de 1 ao total de compartimentos dos veículos), CODPROD (identificador do produto no PetroW), QTDE (texto, inteiro em litros)}]. Obrigatório: ausente ou vazio = 400. |
curl -s -X POST "$BASE/v1/terceiro/basama/ordem_create?$AUTH" \
-H 'Content-Type: application/json' \
-d '{"ORDEM_CARREGAMENTO": {"CNPJEMPRESA": "00.000.000/0001-00", "TIPO": "C", "DATA": "12/11/2026", "CODTRANSP": "000.000.000-00", "SEQFROTA": "ABC1D23", "SEQFROTACARRETA": "ABC1D24", "SEQFROTATREM": "", "SEQFROTA4": "", "COLETAAMOSTRA": "0", "WEBNUMEROOCCLIENTE": "OC-0001", "OBSERVACAO": "", "COMPARTIMENTACAO_OC": [{"COMPARTIMENTO": "1", "CODPROD": "S10", "QTDE": "10000"}, {"COMPARTIMENTO": "2", "CODPROD": "S10", "QTDE": "15000"}]}}'
Resposta:
{
"status": "ok",
"id_ordem": 123456
}
Erros específicos: 400 — {validation: 'Compartimento #N inválido'}.; 400 — {validation: 'Ordem #X já registrada com o código interno: ...'}.; 400 — erros de validação da ordem ou dos itens.; 400 — {TIPO: Inválido} (diferente de C e D) ou {COMPARTIMENTACAO_OC: Inválido} (ausente ou vazio); 403 — CNPJEMPRESA de outro cliente com perfil cliente; 500 — corpo que não é JSON ou DATA inválida.; 405 — outros métodos..
Cancela ordem pendente no formato SisPetro (Basama). Cancela a ordem ID se ela for do cliente do CNPJEMPRESA e estiver em P (pendente): passa para C (cancelada), com data_hora_cancelada = agora. Respeita o escopo do acesso (ordem de outra filial ou de outro cliente = 403) e exige que CNPJEMPRESA seja o do cliente.
/v1/terceiro/basama/ordem_cancelCancela ordem pendente
Perfis: App, Rede, Filial, Cliente, Pessoa
Corpo (JSON objeto)
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
CNPJEMPRESA |
string | sim | CNPJ do cliente da ordem. |
ID |
string | sim | Id da ordem (texto ou número). |
curl -s -X POST "$BASE/v1/terceiro/basama/ordem_cancel?$AUTH" \
-H 'Content-Type: application/json' \
-d '{"CNPJEMPRESA": "00.000.000/0001-00", "ID": "123456"}'
Resposta:
{
"status": "ok",
"ordem": "Cancelada com sucesso"
}
Erros específicos: 400 — {registro: 'Falha ao cancelar'}: a ordem não existe, é de outro cliente ou não está em P (pendente).; 400 — erro de validação ao gravar.; 400 — corpo ou ID inválido.; 405 — outros métodos..