1. Introdução e Acesso Rápido

Para uma experiência mais interativa e para facilitar os testes, a documentação completa da API está disponível via Swagger UI. Adicionalmente, fornecemos um arquivo `openapi.json` que pode ser importado em ferramentas de teste de API como Postman ou Insomnia.

URL Base da API
https://api1.azsoft.app:9004/
Logo do Swagger

Swagger UI

Navegue e teste todos os endpoints de forma interativa diretamente no seu browser.

Acessar Swagger UI →

Arquivo OpenAPI (JSON)

Importe todas as coleções de endpoints para sua ferramenta de API preferida.

Baixar openapi.json →

2. Autenticação

A autenticação é baseada em chave de API. Inclua a chave no header `x-api-key` em todas as requisições.

x-api-key: SUA_CHAVE_DE_API

A Chave de API é única e gerada conforme a solicitação da empresa em contato com a AZSoft. Ela tem níveis de acesso, onde pode servir apenas para acessar os endpoints de Motorista, Viagem e Veiculos, ou todos os módulos.

Respostas de Autenticação e Autorização

401 Unauthorized - Chave de API não fornecida.

{ "detail": "Chave de API não fornecida" }

401 Unauthorized - Chave de API inválida.

{ "detail": "Chave de API inválida" }

403 Forbidden - Chave de API desativada.

{ "detail": "A API Key está desativada." }

3. Endpoints

3.1. Acompanhamento de Viagem

Verificação de Permissão

Para acessar qualquer endpoint deste módulo, a Chave de API utilizada deve ter permissão para recursos de viagem. Caso contrário, a seguinte resposta será retornada: 

{ "detail": "A API Key não tem permissão para acessar recursos de viagem." }

Modelo de Dados: Viagem

Estrutura de dados para criar e atualizar viagens. Todos os campos são opcionais para criar um novo registro. A obrigatoriedade para atualização será detalhada na seção do endpoint `PUT`.

Campo Tipo Descrição
dt_atual datetime Data de atualização da viagem
nr_cpf_motorista string CPF do motorista
nr_cpf_cnpj_proprietario string CPF/CNPJ do proprietário
nr_cpf_cnpj_transportadora string CPF/CNPJ da transportadora

POST /viagem

Cria um novo registro de viagem. O envio dos dados é feito via `application/json` e todos os campos são opcionais.

Requisição `cURL` de Exemplo:
curl -X POST "URL_BASE/viagem" \ -H "x-api-key: SUA_CHAVE_DE_API" \ -H "Content-Type: application/json" \ -d '{ "on_ativo": true, "nr_cpf_motorista": "nome_teste" }'
Respostas

201 Created - Sucesso. Retorna um JSON com os dados da viagem cadastrada.

{
    "id_cad_viagens": 1120747,
    "dt_inclusao": "2025-05-21 10:21:19.13",
    "message": "success"
}

400 Bad Request - Erro de validação (Ex: tipo de arquivo não suportado).

{
    "detail": "Tipo de arquivo não suportado. Apenas imagens (jpeg, png) e PDF são permitidos."
}

400 Bad Request - Erro de Validação - Campo tp_documento obrigatório quando vincula-se um documento.

{
    "detail": O campo 'tp_documento' é obrigatório quando um 'documento' é fornecido."
}

400 Bad Request - Erro de validação (Ex: violação de regras de campo).

{
    "status": "error",
    "message": "Dados de entrada inválidos.",
    "errors": [
        {
            "field": "sg_uf_entrega",
            "message": "O campo 'sg_uf_entrega' excede o limite de caracteres permitido. Limite: 2.",
            "code": "string_too_long"
        }
    ]
}

500 Internal Server Error - Erro interno no servidor.

{
    "detail": "Detalhes do erro interno."
}

PUT /viagem

Atualiza uma viagem existente. O corpo da requisição é enviado como `application/json`.

Identificação do Registro

Para identificar a viagem a ser atualizada, a API utiliza os seguintes campos do corpo da requisição: `id_cad_viagens`,`nr_oc`, `nr_cte`, e `nr_cnpj_cpf_filial`.

  • Se `id_cad_viagens` for informado, ele será usado como critério principal de Identificação.
  • Se `id_cad_viagens` não for informado, os campos `nr_cnpj_cpf_filial` e `nr_cte` ou `nr_oc` e `nr_cnpj_cpf_filial` se tornam obrigatórios.
  • É preciso informar um dos conjuntos de pesquisa para identificar o registro e fazer a atualização das informações.

Requisição `cURL` de Exemplo:
curl -X PUT "URL_BASE/viagem" \ -H "x-api-key: SUA_CHAVE_DE_API" \ -H "Content-Type: application/json" \ -d '{ "nr_oc": 19299, "nr_cnpj_cpf_filial": "12345678", "nm_coleta": "teste", "sg_uf_coleta": "MT", ... }'
Respostas

200 OK - Sucesso. Retorna um JSON com os dados da viagem atualizada.

{
    "dt_atual": "2023-05-21 10:21:19",
    "nr_viagem_interna": 2002,
    "dt_viagem_emissao": "2024-05-21 10:21:19.13",
    "st_cte": "2",
    ...
}

400 Bad Request - Critérios de busca insuficientes.

{
    "detail": "Pelo menos um critério de busca (nr_cnpj_cpf_filial, nr_cte, nr_oc) deve ser fornecido para identificar a viagem."
}

400 Bad Request - Campos obrigatórios ausentes.

{
    "detail": "nr_cte, nr_cnpj_cpj_filial são obrigatórios e não podem ser nulos ou vazios."
}

400 Bad Request - Erro de validação de campo.

{
    "status": "error",
    "message": "Dados de entrada inválidos.",
    "errors": [
        {
            "field": "sg_uf_entrega",
            "message": "O campo 'sg_uf_entrega' excede o limite de caracteres permitido. Limite: 2.",
            "code": "string_too_long"
        }
    ]
}

404 Not Found - Viagem não encontrada.

{
    "detail": "Viagem não encontrada com os critérios fornecidos."
}

500 Internal Server Error - Erro interno no servidor.

{
    "detail": "Detalhes do erro interno."
}

3.2. Cadastro de Motorista

Verificação de Permissão

Para acessar qualquer endpoint deste módulo, a Chave de API utilizada deve ter permissão para recursos do motorista. Caso contrário, a seguinte resposta será retornada: 

{ "detail": "A API Key não tem permissão para acessar recursos do motorista" }

Modelo de Dados: Motorista

Estrutura de dados para criar e atualizar motoristas.

Campo Tipo Descrição
dt_atual datetime Data de atualização do cadastro
dt_nascimento date Data de nascimento do motorista
nr_cpf string CPF do motorista
nm_nome string Nome completo do motorista

POST /motorista

Cria um novo cadastro de motorista. Todos os campos são opcionais e o envio é em `multipart/form-data`.

Requisição `cURL` de Exemplo:
curl -X POST "URL_BASE/motorista" \ -H "x-api-key: SUA_CHAVE_DE_API" \ -F "nr_cpf=123.456.789-00" \ -F "nm_nome=Motorista Teste" \ -F "documento=@/path/to/cnh.pdf"
Respostas

201 Created - Sucesso. Retorna um JSON com os dados do motorista cadastrado.

{
    "nr_cpf": "123.456.789-00",
    "dt_inclusao": "2025-06-07T15:30:00.123456",
    "nm_nome": "Motorista Teste",
    "cnh_numero": "09876543210",
    ...
}

400 Bad Request - Erro de validação de campo.

{
    "status": "error",
    "message": "Dados de entrada inválidos.",
    "errors": [
        {
            "field": "cnh_uf",
            "message": "O campo 'cnh_uf' excede o limite de caracteres permitido. Limite: 2.",
            "code": "string_too_long"
        }
    ]
}

400 Bad Request - Erro de Validação - Campo tp_documento obrigatório quando vincula-se um documento.

{
    "detail": O campo 'tp_documento' é obrigatório quando um 'documento' é fornecido."
}

500 Internal Server Error - Erro interno no servidor.

{
    "detail": "Detalhes do erro interno."
}

PUT /motorista/{cpf}

Atualiza os dados de um motorista existente, identificado pelo CPF na URL. O corpo da requisição é enviado como `application/json`.

Requisição `cURL` de Exemplo:
curl -X PUT "URL_BASE/motorista/12345678900" \ -H "x-api-key: SUA_CHAVE_DE_API" \ -H "Content-Type: application/json" \ -d '{"nr_celular1": "11987654321"}'
Respostas

200 OK - Sucesso. Retorna um JSON com os dados do motorista atualizado.

{
    "nr_cpf": "123.456.789-00",
    "nm_nome": "Motorista Teste",
    "cnh_numero": "09876543210",
    "dt_inclusao": "2025-06-07T15:30:00.123456",
    ...
}

400 Bad Request - Erro de validação de campo.

{
    "status": "error",
    "message": "Dados de entrada inválidos.",
    "errors": [
        {
            "field": "cnh_uf",
            "message": "O campo 'cnh_uf' excede o limite de caracteres permitido. Limite: 2.",
            "code": "string_too_long"
        }
    ]
}

404 Not Found - Motorista não encontrado.

{
    "detail": "Motorista não encontrado com os critérios fornecidos."
}

500 Internal Server Error - Erro interno no servidor.

{
    "detail": "Detalhes do erro interno."
}

POST /documento

Envio de documentos. O corpo da requisição é enviado como `multipart/form-data`.

Anexando Documentos

Deve-se enviar o arquivo vinculando o nome `documento` (tipo `File`) no corpo da requisição.
Formatos permitidos: Imagens (jpeg, png) e PDF.


Informações

É restrito vincular o tp_documento e orig_modulo, podendo vincular conforme as tabelas abaixo.

Tipos de Modulos (`orig_modulo`)
orig_modulo Descrição
cad_veiculoReferente ao módulo de Veiculos
cad_viagemReferente ao módulo de Viagens
cad_motoristaReferente ao módulo de Motoristas
Tipos de Documento Aceitos (`tp_documento`)
tp_documento Descrição
CNHDocumento oficial que atesta a aptidão do motorista para dirigir.
MOOPCertificado do curso obrigatório para transporte de cargas perigosas.
ASOComprovante da aptidão médica do trabalhador para a função.
COMP_ENDDocumento que comprova o endereço residencial do motorista ou proprietário.
FOTO_PERFILImagem do rosto do motorista para identificação no sistema.
CRLVDocumento anual de porte obrigatório do veículo.
FOTO_PLACA_DIANTFotografia da placa de identificação dianteira do veículo.
FOTO_TRASEIRAFotografia da parte traseira do veículo (pode incluir a placa).
COMP_DESCDocumento que comprova a entrega e descarga da mercadoria.
TICKET_GERALComprovante de pagamento de serviços como pedágio, balança, etc.
ROMANEIOLista detalhada da carga, utilizada para conferência e transporte.
CANHOTO_NFEParte destacável da NFe que comprova o recebimento da mercadoria.
CANHOTO_CTEParte destacável do CTe que comprova o recebimento do serviço de transporte.
CIOTCódigo único para identificação do pagamento do frete ao transportador.
ORDEM_COLETADocumento que autoriza e detalha a coleta de mercadoria.
OC_CLIENTEOrdem de coleta específica emitida ou referente ao cliente final.
TICKET_BALSAComprovante de pagamento da travessia em balsa.
COMP_BANCOComprovante de conta bancária para fins de pagamento ou cadastro.
FOTO_VEICULOFotografia geral do veículo para registro.
OUTROOutro tipo de documento.
Requisição `cURL` de Exemplo:
curl -X POST "URL_BASE/documento" \ -H "x-api-key: SUA_CHAVE_DE_API" \ -H "Content-Type: multipart/form-data" \ -F "documento=@/caminho/do/seu/arquivo/aqui/arquivo.png" \ -F "empresa_cnpj=string" \ -F "tp_documento=string" \ -F "orig_modulo=string" \ -F "ident_inclusao=string" \ -F "id_registro_origem=0" \ -F "descricao=string" '
Respostas

200 OK - Sucesso. Retorna um JSON com os dados do upload do documento.

{
  "data_upload": "2025-07-01T14:30:00",
  "data_inclusao": "2025-07-01T10:00:00",
  "nm_arquivo": "CNH.pdf",
  "empresa_cnpj": "12345678000199",
  "tp_documento": "CNH",
  "orig_modulo": "cad_viagem",
  "id_registro_origem": 123456
}

400 Bad Request - Campo de documento obrigatório

{
    "detail": "Documento obrigatório.
}

400 Bad Request - Campo tp_documento obrigatório.

{
    "detail": "O campo 'tp_documento' é obrigatório."
}

400 Bad Request - Tipo de arquivo não suportado

{
    "detail": "Tipo de arquivo não suportado. Apenas imagens (jpeg, png) e PDF são permitidos."
}

400 Bad Request - Quando se vincula no campo orig_modulo um valor que não confere aos módulos existentes.

{
    "detail": "Informe o orig_modulo válido. Outro_modulo não aceito."
}

400 Bad Request - Quando é vinculado tp_documento o valor OUTRO, o campo 'descricao' se torna obrigatório.

{
    "detail": "Campo 'descricao' obrigatório."
}

400 Bad Request - Erro de validação de campo.

{
    "status": "error",
    "message": "Dados de entrada inválidos.",
    "errors": [
        {
            "field": "tp_documento",
            "message": "O campo 'tp_documento' excede o limite de caracteres permitido",
            "code": "string_too_long"
        }
    ]
}

404 Not Found - Viagem não encontrada.

{
    "detail": "Viagem não encontrada com os critérios fornecidos."
}

500 Internal Server Error - Erro interno no servidor.

{
    "detail": "Detalhes do erro interno."
}

3.4. Cadastro de Veiculos

Verificação de Permissão

Para acessar qualquer endpoint deste módulo, a Chave de API utilizada deve ter permissão para recursos do veiculo. Caso contrário, a seguinte resposta será retornada: 

{ "detail": "A API Key não tem permissão para acessar recursos do veiculo" }

Modelo de Dados: Veiculos

Estrutura de dados para criar e atualizar veiculos.

Campo Tipo Descrição
cpf_motoristastringCPF do motorista vinculado.
cpf_cnpj_proprietariostringCPF ou CNPJ do proprietário do veículo.
placa_cavalostringPlaca do veículo cavalo.
placa_carreta1stringPlaca da primeira carreta.

POST /veiculo

Cria um novo cadastro de veiculo. Todos os campos são opcionais e o envio é em `application/json`.

Requisição `cURL` de Exemplo:
curl -X POST "URL_BASE/veiculo" \ -H "x-api-key: SUA_CHAVE_DE_API" \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ -d '{ "cpf_motorista": "string", "cpf_cnpj_proprietario": "string", "placa_cavalo": "string", "placa_carreta1": "string", ... }'
Respostas

201 Created - Sucesso. Retorna um JSON com os dados do veiculo cadastrado.

{
    "cpf_motorista": "123.456.789-00",
    "dt_inclusao": "2025-06-07T15:30:00.123456",
    "placa_carreta4": "ABC123",
    "tp_veiculo": "string",
    ...
}

400 Bad Request - Erro de validação de campo.

{
    "status": "error",
    "message": "Dados de entrada inválidos.",
    "errors": [
        {
            "field": "placa_cavalo",
            "message": "O campo 'placa_cavalo' excede o limite de caracteres permitido. Limite: 7.",
            "code": "string_too_long"
        }
    ]
}

500 Internal Server Error - Erro interno no servidor.

{
    "detail": "Detalhes do erro interno."
}

PUT /veiculo/{cpf_cnpj_proprietario}

Atualiza os dados de um veiculo existente, identificado pelo valor referente ao cpf_cnpj_proprietario na URL. O corpo da requisição é enviado como `application/json`.

Requisição `cURL` de Exemplo:
curl -X PUT "URL_BASE/veiculo/12345678900" \ -H "x-api-key: SUA_CHAVE_DE_API" \ -H "Content-Type: application/json" \ -d '{"placa_cavalo": "ABB112"}'
Respostas

200 OK - Sucesso. Retorna um JSON com os dados do veiculo atualizado.

{
    "cpf_motorista": "123.456.789-00",
    "dt_inclusao": "2025-06-07T15:30:00.123456",
    "placa_carreta4": "ABC123",
    "tp_veiculo": "string",
    ...
}

400 Bad Request - Erro de validação de campo.

{
    "status": "error",
    "message": "Dados de entrada inválidos.",
    "errors": [
        {
            "field": "cnh_uf",
            "message": "O campo 'cnh_uf' excede o limite de caracteres permitido. Limite: 2.",
            "code": "string_too_long"
        }
    ]
}

404 Not Found - Veiculo não encontrado.

{
    "detail": "Veiculo não encontrado com os critérios fornecidos."
}

500 Internal Server Error - Erro interno no servidor.

{
    "detail": "Detalhes do erro interno."
}